org.apache.commons.geometry.io.euclidean.threed.txt

Class TextFacetDefinitionWriter

java.lang.Object

org.apache.commons.geometry.io.core.utils.AbstractTextFormatWriter

org.apache.commons.geometry.io.euclidean.threed.txt.TextFacetDefinitionWriter

All Implemented Interfaces:

Closeable, AutoCloseable

public class TextFacetDefinitionWriter
extends AbstractTextFormatWriter

Class for writing 3D facet geometry in a simple human-readable text format. The format simply consists of sequences of decimal numbers defining the vertices of each facet, with one facet defined per line. Facet vertices are defined by listing their x, y, and z components in that order. At least 3 vertices are required for each facet but more can be specified. The facet normal is defined implicitly from the facet vertices using the right-hand rule (i.e. vertices are arranged counter-clockwise).

Delimiters can be configured for both vertex components and vertices. This allows a wide range of outputs to be configured, from standard CSV format to formats designed for easy human readability.

Examples

The examples below demonstrate output from two square facets using different writer configurations.

Default

The default writer configuration uses distinct vertex and vertex component separators to make it easier to visually distinguish vertices. Comments are supported and facets are allowed to have any geometrically valid number of vertices. This format is designed for human readability and ease of editing.

 # two square facets
 0 0 0; 1 0 0; 1 1 0; 0 1 0
 0 0 0; 0 1 0; 0 1 1; 0 0 1
 

CSV

The example below uses a comma as both the vertex and vertex component separators to produce a standard CSV format. The facet vertex count is set to 3 to ensure that each row has the same number of columns and all numbers are written with at least a single fraction digit to ensure proper interpretation as floating point data. Comments are not supported. This configuration is produced by the csvFormat(Writer) factory method.

 0.0,0.0,0.0,1.0,0.0,0.0,1.0,1.0,0.0
 0.0,0.0,0.0,1.0,1.0,0.0,0.0,1.0,0.0
 0.0,0.0,0.0,0.0,1.0,0.0,0.0,1.0,1.0
 0.0,0.0,0.0,0.0,1.0,1.0,0.0,0.0,1.0
 

See Also:

TextFacetDefinitionReader

Constructor Summary

Constructors

Constructor and Description
TextFacetDefinitionWriter(Writer writer) Construct a new instance that writes facet information to the given writer.

Method Summary

Modifier and Type	Method and Description
static TextFacetDefinitionWriter	csvFormat(Writer writer) Construct a new instance configured to write CSV output to the given writer.
String	getCommentToken() Get the string used to begin comment lines in the output.
int	getFacetVertexCount() Get the number of vertices required per facet or -1 if no specific number is required.
String	getVertexComponentSeparator() Get the string used to separate vertex components (ie, individual x, y, z values).
String	getVertexSeparator() Get the string used to separate facet vertices.
void	setCommentToken(String commentToken) Set the string used to begin comment lines in the output.
void	setFacetVertexCount(int vertexCount) Set the number of vertices required per facet.
void	setVertexComponentSeparator(String sep) Set the string used to separate vertex components (ie, individual x, y, z values).
void	setVertexSeparator(String sep) Set the string used to separate facet vertices.
void	write(BoundarySource3D src) Write all boundaries in the argument to the output.
void	write(FacetDefinition facet) Write the vertices in the argument to the output.
void	write(List<Vector3D> vertices) Write a list of vertices defining a facet as a single line of text to the output.
void	write(PlaneConvexSubset convexSubset) Write the vertices defining the argument to the output.
void	writeBlankLine() Write a blank line to the output.
void	writeComment(String comment) Write a comment to the output.

Methods inherited from class org.apache.commons.geometry.io.core.utils.AbstractTextFormatWriter

close, getDoubleFormat, getLineSeparator, getWriter, setDoubleFormat, setLineSeparator, write, write, write, write, writeNewLine

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TextFacetDefinitionWriter

public TextFacetDefinitionWriter(Writer writer)

Construct a new instance that writes facet information to the given writer.

Parameters:

writer - writer to write output to

Method Detail

getVertexComponentSeparator

public String getVertexComponentSeparator()

Get the string used to separate vertex components (ie, individual x, y, z values). The default value is .

Returns:

string used to separate vertex components

setVertexComponentSeparator

public void setVertexComponentSeparator(String sep)

Set the string used to separate vertex components (ie, individual x, y, z values).

Parameters:

sep - string used to separate vertex components

getVertexSeparator

public String getVertexSeparator()

Get the string used to separate facet vertices. The default value is .

Returns:

string used to separate facet vertices

setVertexSeparator

public void setVertexSeparator(String sep)

Set the string used to separate facet vertices.

Parameters:

sep - string used to separate facet vertices

getFacetVertexCount

public int getFacetVertexCount()

Get the number of vertices required per facet or -1 if no specific number is required. The default value is .

Returns:

the number of vertices required per facet or -1 if any geometricallly valid number is allowed (ie, any number greater than or equal to 3)

setFacetVertexCount

public void setFacetVertexCount(int vertexCount)

Set the number of vertices required per facet. This can be used to enforce a consistent format in the output. Set to -1 to allow any geometrically valid number of vertices (ie, any number greater than or equal to 3).

Parameters:

vertexCount - number of vertices required per facet or -1 to allow any number

Throws:

IllegalArgumentException - if the argument would produce invalid geometries (ie, is greater than -1 and less than 3)

getCommentToken

public String getCommentToken()

Get the string used to begin comment lines in the output. The default value is

Returns:

the string used to begin comment lines in the output; may be null

setCommentToken

public void setCommentToken(String commentToken)

Set the string used to begin comment lines in the output. Set to null to disable the use of comments.

Parameters:

commentToken - comment token string

Throws:

IllegalArgumentException - if the argument is empty or begins with whitespace

writeComment

public void writeComment(String comment)

Write a comment to the output.

Parameters:

comment - comment string to write

Throws:

IllegalStateException - if the configured comment token is null

UncheckedIOException - if an I/O error occurs

writeBlankLine

public void writeBlankLine()

Write a blank line to the output.

Throws:

UncheckedIOException - if an I/O error occurs

write

public void write(BoundarySource3D src)

Write all boundaries in the argument to the output. If the facet vertex count has been set to 3, then each boundary is converted to triangles before being written. Otherwise, the boundaries are written as-is.

Parameters:

src - object providing the boundaries to write

Throws:

IllegalArgumentException - if any boundary has infinite size or a facet vertex count has been configured and a boundary cannot be represented using the required number of vertices

UncheckedIOException - if an I/O error occurs

write

public void write(PlaneConvexSubset convexSubset)

Write the vertices defining the argument to the output. If the facet vertex count has been set to 3, then the convex subset is converted to triangles before being written to the output. Otherwise, the argument vertices are written as-is.

Parameters:

convexSubset - convex subset to write

Throws:

IllegalArgumentException - if the argument has infinite size or a facet vertex count has been configured and the number of required vertices does not match the number present in the argument

UncheckedIOException - if an I/O error occurs

write

public void write(FacetDefinition facet)

Write the vertices in the argument to the output.

Parameters:

facet - facet containing the vertices to write

Throws:

IllegalArgumentException - if a facet vertex count has been configured and the number of required vertices does not match the number present in the argument

UncheckedIOException - if an I/O error occurs

write

public void write(List<Vector3D> vertices)

Write a list of vertices defining a facet as a single line of text to the output. Vertex components (ie, individual x, y, z values) are separated with the configured vertex component separator and vertices are separated with the configured vertex separator.

Parameters:

vertices - vertices to write

Throws:

IllegalArgumentException - if the vertex list contains less than 3 vertices or a facet vertex count has been configured and the number of required vertices does not match the number given

UncheckedIOException - if an I/O error occurs

See Also:

getVertexComponentSeparator(), getVertexSeparator(), getFacetVertexCount()

csvFormat

public static TextFacetDefinitionWriter csvFormat(Writer writer)

Construct a new instance configured to write CSV output to the given writer. The returned instance has the following configuration:

• Vertex separator and vertex components separator are set to the "," string.
• Comments are disabled (i.e., comment token is set to null).
• Facet vertex count is set to 3 to ensure a consistent number of columns.

This configuration produces output similar to the following:

 0.0,0.0,0.0,1.0,0.0,0.0,1.0,1.0,0.0
 0.0,0.0,0.0,1.0,1.0,0.0,0.0,1.0,0.0
 

Parameters:

writer - writer to write output to

Returns:

a new facet definition writer configured to produce CSV output