Package org.tinfour.utils.loaders

Class VertexReaderText

  • All Implemented Interfaces:
    Closeable, AutoCloseable, IVertexReader
    public class VertexReaderText
extends Object
implements Closeable, IVertexReader
    A utility for loading vertices from a file for testing. The coordinates for vertices are expected to be loaded as three numeric values separated by a delimiter character.

    Comment Lines: Lines beginning with a "hash sign", or #, will be treated as comments and ignored. Blank lines will be ignored.

    Delimiters: Specifications in text files depend on the presence of a delimiter character to separate data fields given on a line of text. Typically delimiters are specified using a space, tab, comma, or vertical-bar character (pipe). Files with the extension ".csv" (for comma-separated-value) are assumed to be comma-delimited. Otherwise, the constructor will attempt to inspect the content of the specified file and determine the delimiter based on internal clues. If a file includes a mix of potential delimiters, such as both spaces and commas, the delimiter will be determined on the basis of precedence. Supported delimiters, in increasing order of precedence, are comma, space, tab, and vertical bar.

    An application may also override the automatically determined delimiter through the setDelimiter() method.

    Column Headers: By default, columns in the file are treated as giving x, y, and z coordinates in that order. The order of the coordinate specifications can be altered through the use of column headers. If the first non-comment line in a file contains non-numeric specifications, the line will be treated as a "header" line that gives the names of columns.

    Geographic Coordinates: While this class is not sufficient for Geographic Information Systems (GIS), it does provide minimal support for geographic coordinates. If the values in the file are to be treated as geographic coordinates, the input file must include a header row indicating which columns are latitude and longitude. This feature serves two purposes, it informs the model that the coordinates are geographic and it dispels any ambiguity about which column is which. Geographic coordinate values must be giving in standard decimal numeric form using negative numbers for southern latitudes and western longitudes (the quadrant characters N, S, E, W, and the degrees-minutes-seconds notion are not supported at this time).

    For example: 

    
    latitude, longitude, z
      42.5,     73.33,   2001

    Note, however that if both geographic and Cartesian coordinates are provided, the Cartesian coordinates will take precedence. The rationale, for this design decision is that specifications of this type are usually encountered in cases where data from geographic sources have be projected to a planar coordinate system.

    Linear Units: Although a specification of units for the values in the source file is not supported by the text format, applications can specify linear units through the use of the setLinearUnits() method. The primary use for this feature is in the case of geographic coordinates. Linear units are used to scale coordinates when geographic coordinates (latitude, longitude) are transformed to Cartesian (planar) coordinates.

    • Constructor Detail

      • VertexReaderText

        public VertexReaderText​(File file)
                 throws IOException
        Constructs an instance of a text-based vertex reader for the specified file and determines the delimiter to be used for separating columns.
        Parameters:
        file - a reference to the file containing the text from which vertices are to be parsed.
        Throws:
        IOException - in the event of an unrecoverable I/O error.

    • Method Detail

      • setVerticalCoordinateTransform

        public void setVerticalCoordinateTransform​(IVerticalCoordinateTransform verticalCoordinateTransform)
        Sets a coordinate transform to be applied when reading vertical coordinates (z coordinates).
        Parameters:
        verticalCoordinateTransform - a valid instance.

      • setTargetHeaders

        public void setTargetHeaders​(String[] targetHeaders)
        Sets an array of strings to be used as the target headers for the x, y, and z columns.
        Parameters:
        targetHeaders - an array of 3 valid, non-empty strings

      • read

        public List<Vertex> read​(IMonitorWithCancellation monitor)
                  throws IOException
        Description copied from interface: IVertexReader
        Read a collection of vertices from the data source associated with the current implementation and instance.

        Monitoring Progress of the Read Because some input sources can produce quite a large number of vertices and may require several seconds for load operations, this interface supports an optional monitor object. Implementation classes are not required to support monitors, but should do so if it is feasible. The Tinfour monitor is intended to support two operations. First, it provides a read operation a mechanism for advising the calling application on the status of its progress. Second, it provides the calling application a mechanism for canceling a read operation. These operations are generally used in support of a user interface, but may have other applications.

        All implementations are expected to implement logic to handle a null monitor reference.

        Specified by:
        read in interface IVertexReader
        Parameters:
        monitor - a valid instance or a null if no monitoring is desired.
        Returns:
        a valid, potentially list
        Throws:
        IOException - in the event of unreadable data or I/O access exceptions.

      • getDelimiter

        public char getDelimiter()
        Gets the delimiter character for a file. Normally, this delimiter is determined in the constructor, but it can be set by applications if desired.
        Returns:
        a valid character or a zero if no delimiter could be determined (in which case, the file is treated as unreadable)

      • setDelimiter

        public void setDelimiter​(char delimiter)
        Sets the delimiter character for a file.
        Parameters:
        delimiter - a valid character

      • getXMin

        public double getXMin()
        Gets the minimum x coordinate in the sample
        Specified by:
        getXMin in interface IVertexReader
        Returns:
        a valid floating point value

      • getXMax

        public double getXMax()
        Gets the maximum x coordinate in the sample
        Specified by:
        getXMax in interface IVertexReader
        Returns:
        a valid floating point value

      • getYMin

        public double getYMin()
        Gets the minimum y coordinate in the sample
        Specified by:
        getYMin in interface IVertexReader
        Returns:
        a valid floating point value

      • getYMax

        public double getYMax()
        Gets the maximum y coordinate in the sample
        Specified by:
        getYMax in interface IVertexReader
        Returns:
        a valid floating point value

      • getZMin

        public double getZMin()
        Gets the minimum z coordinate in the sample
        Specified by:
        getZMin in interface IVertexReader
        Returns:
        a valid floating point value

      • getZMax

        public double getZMax()
        Gets the maximum z coordinate in the sample
        Specified by:
        getZMax in interface IVertexReader
        Returns:
        a valid floating point value

      • isSourceInGeographicCoordinates

        public boolean isSourceInGeographicCoordinates()
        Indicates whether the source data was in geographic coordinates
        Specified by:
        isSourceInGeographicCoordinates in interface IVertexReader
        Returns:
        true if the source data used geographic coordinates; otherwise, false.

      • getLinearUnits

        public LinearUnits getLinearUnits()
        Gets the linear units for the coordinate system used by the data. It is assumed that the vertical and horizontal coordinate systems will be in the same unit system, though assumption could change in a future implementation.
        Returns:
        a valid enumeration instance

      • setLinearUnits

        public void setLinearUnits​(LinearUnits linearUnits)
        Sets the linear units for the coordinate system used by the horizontal (x and y) coordinates of the data. This method is intended for cases when the application can provide information that is not otherwise available in the source data.
        Parameters:
        linearUnits - a valid instance

      • getCoordinateTransform

        public ICoordinateTransform getCoordinateTransform()
        Gets the coordinate transform associated with this instance. May be null if no coordinate transform was set.
        Specified by:
        getCoordinateTransform in interface IVertexReader
        Returns:
        a valid transform or a null if none was set.

      • setCoordinateTransform

        public void setCoordinateTransform​(ICoordinateTransform transform)
        Sets a coordinate transform to be used for mapping values from the source file to vertex coordinates.
        Specified by:
        setCoordinateTransform in interface IVertexReader
        Parameters:
        transform - a valid transform or a null if none is to be applied.