Package 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:

  • Field Details

    • CSV_SEPARATOR

      static final String CSV_SEPARATOR
      Vertex and vertex component separator used in the CSV format.
      See Also:

    • CSV_FACET_VERTEX_COUNT

      static final int CSV_FACET_VERTEX_COUNT
      Number of vertices required per facet in the CSV format.
      See Also:

    • DEFAULT_VERTEX_COMPONENT_SEPARATOR

      static final String DEFAULT_VERTEX_COMPONENT_SEPARATOR
      Default vertex component separator.
      See Also:

    • DEFAULT_VERTEX_SEPARATOR

      static final String DEFAULT_VERTEX_SEPARATOR
      Default vertex separator.
      See Also:

    • DEFAULT_FACET_VERTEX_COUNT

      static final int DEFAULT_FACET_VERTEX_COUNT
      Default facet vertex count.
      See Also:

    • DEFAULT_COMMENT_TOKEN

      private static final String DEFAULT_COMMENT_TOKEN
      Default comment token.
      See Also:

    • vertexComponentSeparator

      private String vertexComponentSeparator
      String used to separate vertex components, ie, x, y, z values.

    • vertexSeparator

      private String vertexSeparator
      String used to separate vertices.

    • facetVertexCount

      private int facetVertexCount
      Number of vertices required per facet; will be -1 if disabled.

    • commentToken

      private String commentToken
      Comment start token; may be null.

  • Constructor Details

    • 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 Details

    • 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 -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:
      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:

    • write

      private void write(Vector3D vertex)
      Write a single vertex to the output.
      Parameters:
      vertex - vertex to write
      Throws:
      UncheckedIOException - if an I/O error occurs

    • 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