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:
java.io.Closeable
,java.lang.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 theirx
,y
, andz
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
andvertices
. This allows a wide range of outputs to be configured, from standardCSV 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
-
-
Field Summary
Fields Modifier and Type Field Description private java.lang.String
commentToken
Comment start token; may be null.(package private) static int
CSV_FACET_VERTEX_COUNT
Number of vertices required per facet in the CSV format.(package private) static java.lang.String
CSV_SEPARATOR
Vertex and vertex component separator used in the CSV format.private static java.lang.String
DEFAULT_COMMENT_TOKEN
Default comment token.(package private) static int
DEFAULT_FACET_VERTEX_COUNT
Default facet vertex count.(package private) static java.lang.String
DEFAULT_VERTEX_COMPONENT_SEPARATOR
Default vertex component separator.(package private) static java.lang.String
DEFAULT_VERTEX_SEPARATOR
Default vertex separator.private int
facetVertexCount
Number of vertices required per facet; will be -1 if disabled.private java.lang.String
vertexComponentSeparator
String used to separate vertex components, ie, x, y, z values.private java.lang.String
vertexSeparator
String used to separate vertices.
-
Constructor Summary
Constructors Constructor Description TextFacetDefinitionWriter(java.io.Writer writer)
Construct a new instance that writes facet information to the given writer.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static TextFacetDefinitionWriter
csvFormat(java.io.Writer writer)
Construct a new instance configured to write CSV output to the given writer.java.lang.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.java.lang.String
getVertexComponentSeparator()
Get the string used to separate vertex components (ie, individual x, y, z values).java.lang.String
getVertexSeparator()
Get the string used to separate facet vertices.void
setCommentToken(java.lang.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(java.lang.String sep)
Set the string used to separate vertex components (ie, individual x, y, z values).void
setVertexSeparator(java.lang.String sep)
Set the string used to separate facet vertices.void
write(java.util.List<Vector3D> vertices)
Write a list of vertices defining a facet as a single line of text to the output.void
write(BoundarySource3D src)
Write all boundaries in the argument to the output.void
write(PlaneConvexSubset convexSubset)
Write the vertices defining the argument to the output.private void
write(Vector3D vertex)
Write a single vertex to the output.void
write(FacetDefinition facet)
Write the vertices in the argument to the output.void
writeBlankLine()
Write a blank line to the output.void
writeComment(java.lang.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
-
-
-
-
Field Detail
-
CSV_SEPARATOR
static final java.lang.String CSV_SEPARATOR
Vertex and vertex component separator used in the CSV format.- See Also:
- Constant Field Values
-
CSV_FACET_VERTEX_COUNT
static final int CSV_FACET_VERTEX_COUNT
Number of vertices required per facet in the CSV format.- See Also:
- Constant Field Values
-
DEFAULT_VERTEX_COMPONENT_SEPARATOR
static final java.lang.String DEFAULT_VERTEX_COMPONENT_SEPARATOR
Default vertex component separator.- See Also:
- Constant Field Values
-
DEFAULT_VERTEX_SEPARATOR
static final java.lang.String DEFAULT_VERTEX_SEPARATOR
Default vertex separator.- See Also:
- Constant Field Values
-
DEFAULT_FACET_VERTEX_COUNT
static final int DEFAULT_FACET_VERTEX_COUNT
Default facet vertex count.- See Also:
- Constant Field Values
-
DEFAULT_COMMENT_TOKEN
private static final java.lang.String DEFAULT_COMMENT_TOKEN
Default comment token.- See Also:
- Constant Field Values
-
vertexComponentSeparator
private java.lang.String vertexComponentSeparator
String used to separate vertex components, ie, x, y, z values.
-
vertexSeparator
private java.lang.String vertexSeparator
String used to separate vertices.
-
facetVertexCount
private int facetVertexCount
Number of vertices required per facet; will be -1 if disabled.
-
commentToken
private java.lang.String commentToken
Comment start token; may be null.
-
-
Method Detail
-
getVertexComponentSeparator
public java.lang.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(java.lang.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 java.lang.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(java.lang.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 -1.- 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:
java.lang.IllegalArgumentException
- if the argument would produce invalid geometries (ie, is greater than -1 and less than 3)
-
getCommentToken
public java.lang.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(java.lang.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:
java.lang.IllegalArgumentException
- if the argument is empty or begins with whitespace
-
writeComment
public void writeComment(java.lang.String comment)
Write a comment to the output.- Parameters:
comment
- comment string to write- Throws:
java.lang.IllegalStateException
- if the configuredcomment token
is nulljava.io.UncheckedIOException
- if an I/O error occurs
-
writeBlankLine
public void writeBlankLine()
Write a blank line to the output.- Throws:
java.io.UncheckedIOException
- if an I/O error occurs
-
write
public void write(BoundarySource3D src)
Write all boundaries in the argument to the output. If thefacet vertex count
has been set to3
, 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:
java.lang.IllegalArgumentException
- if any boundary has infinite size or afacet vertex count
has been configured and a boundary cannot be represented using the required number of verticesjava.io.UncheckedIOException
- if an I/O error occurs
-
write
public void write(PlaneConvexSubset convexSubset)
Write the vertices defining the argument to the output. If thefacet vertex count
has been set to3
, 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:
java.lang.IllegalArgumentException
- if the argument has infinite size or afacet vertex count
has been configured and the number of required vertices does not match the number present in the argumentjava.io.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:
java.lang.IllegalArgumentException
- if afacet vertex count
has been configured and the number of required vertices does not match the number present in the argumentjava.io.UncheckedIOException
- if an I/O error occurs
-
write
public void write(java.util.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 configuredvertex component separator
and vertices are separated with the configuredvertex separator
.- Parameters:
vertices
- vertices to write- Throws:
java.lang.IllegalArgumentException
- if the vertex list contains less than 3 vertices or afacet vertex count
has been configured and the number of required vertices does not match the number givenjava.io.UncheckedIOException
- if an I/O error occurs- See Also:
getVertexComponentSeparator()
,getVertexSeparator()
,getFacetVertexCount()
-
write
private void write(Vector3D vertex)
Write a single vertex to the output.- Parameters:
vertex
- vertex to write- Throws:
java.io.UncheckedIOException
- if an I/O error occurs
-
csvFormat
public static TextFacetDefinitionWriter csvFormat(java.io.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.
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
-
-