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

Class 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 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

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

    • Constructor Detail

      • TextFacetDefinitionWriter

        public TextFacetDefinitionWriter​(java.io.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 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 configured comment token is null
        java.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 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:
        java.lang.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
        java.io.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:
        java.lang.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
        java.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 a facet vertex count has been configured and the number of required vertices does not match the number present in the argument
        java.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 configured vertex component separator and vertices are separated with the configured vertex separator.
        Parameters:
        vertices - vertices to write
        Throws:
        java.lang.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
        java.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.
        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