Class EllipsoidTessellator


  • public class EllipsoidTessellator
    extends Object
    Class used to tessellate an interest zone on an ellipsoid in either tiles or grids of geodetic points.

    This class is typically used for Earth Observation missions, in order to create tiles or grids that may be used as the basis of visibility event detectors. Tiles are used when surface-related elements are needed, the tiles created completely cover the zone of interest. Grids are used when point-related elements are needed, the points created lie entirely within the zone of interest.

    One should note that as tessellation essentially creates a 2 dimensional almost Cartesian map, it can never perfectly fulfill geometrical dimensions because neither sphere nor ellipsoid are developable surfaces. This implies that the tesselation will always be distorted, and distortion increases as the size of the zone to be tessellated increases.

    Since:
    7.1
    Author:
    Luc Maisonobe
    • Constructor Detail

      • EllipsoidTessellator

        public EllipsoidTessellator​(OneAxisEllipsoid ellipsoid,
                                    TileAiming aiming,
                                    int quantization)
        Simple constructor.

        The quantization parameter is used internally to adjust points positioning. For example when quantization is set to 4, a complete tile that has 4 corner points separated by the tile lengths will really be computed on a grid containing 25 points (5 rows of 5 points, as each side will be split in 4 segments, hence will have 5 points). This quantization allows rough adjustment to balance margins around the zone of interest and improves geometric accuracy as the along and across directions are readjusted at each points.

        It is recommended to use at least 2 as the quantization parameter for tiling. The rationale is that using only 1 for quantization would imply all points used are tiles vertices, and hence would lead small zones to generate 4 tiles with a shared vertex inside the zone and the 4 tiles covering the four quadrants at North-West, North-East, South-East and South-West. A quantization value of at least 2 allows to shift the tiles so the center point is an inside point rather than a tile vertex, hence allowing a single tile to cover the small zone. A value even greater like 4 or 8 would allow even finer positioning to balance the tiles margins around the zone.

        Parameters:
        ellipsoid - underlying ellipsoid
        aiming - aiming used for orienting tiles
        quantization - number of segments tiles sides are split into for tiles fine positioning
    • Method Detail

      • tessellate

        public List<List<Tile>> tessellate​(SphericalPolygonsSet zone,
                                           double fullWidth,
                                           double fullLength,
                                           double widthOverlap,
                                           double lengthOverlap,
                                           boolean truncateLastWidth,
                                           boolean truncateLastLength)
        Tessellate a zone of interest into tiles.

        The created tiles will completely cover the zone of interest.

        The distance between a vertex at a tile corner and the vertex at the same corner in the next vertex are computed by subtracting the overlap width (resp. overlap length) from the full width (resp. full length). If for example the full width is specified to be 55 km and the overlap in width is specified to be +5 km, successive tiles would span as follows:

        • tile 1 covering from 0 km to 55 km
        • tile 2 covering from 50 km to 105 km
        • tile 3 covering from 100 km to 155 km
        • ...

        In order to achieve the same 50 km step but using a 5 km gap instead of an overlap, one would need to specify the full width to be 45 km and the overlap to be -5 km. With these settings, successive tiles would span as follows:

        • tile 1 covering from 0 km to 45 km
        • tile 2 covering from 50 km to 95 km
        • tile 3 covering from 100 km to 155 km
        • ...
        Parameters:
        zone - zone of interest to tessellate
        fullWidth - full tiles width as a distance on surface, including overlap (in meters)
        fullLength - full tiles length as a distance on surface, including overlap (in meters)
        widthOverlap - overlap between adjacent tiles (in meters), if negative the tiles will have a gap between each other instead of an overlap
        lengthOverlap - overlap between adjacent tiles (in meters), if negative the tiles will have a gap between each other instead of an overlap
        truncateLastWidth - if true, the first tiles strip will be started as close as possible to the zone of interest, and the last tiles strip will have its width reduced to also remain close to the zone of interest; if false all tiles strip will have the same fullWidth and they will be balanced around zone of interest
        truncateLastLength - if true, the first tile in each strip will be started as close as possible to the zone of interest, and the last tile in each strip will have its length reduced to also remain close to the zone of interest; if false all tiles in each strip will have the same fullLength and they will be balanced around zone of interest
        Returns:
        a list of lists of tiles covering the zone of interest, each sub-list corresponding to a part not connected to the other parts (for example for islands)
      • sample

        public List<List<GeodeticPoint>> sample​(SphericalPolygonsSet zone,
                                                double width,
                                                double length)
        Sample a zone of interest into a grid sample of geodetic points.

        The created points will be entirely within the zone of interest.

        Parameters:
        zone - zone of interest to sample
        width - grid sample cells width as a distance on surface (in meters)
        length - grid sample cells length as a distance on surface (in meters)
        Returns:
        a list of lists of points sampling the zone of interest, each sub-list corresponding to a part not connected to the other parts (for example for islands)
      • toGeodetic

        protected GeodeticPoint toGeodetic​(S2Point point)
        Convert a point on the unit 2-sphere to geodetic coordinates.
        Parameters:
        point - point on the unit 2-sphere
        Returns:
        geodetic point (arbitrarily set at altitude 0)
      • buildSimpleZone

        public static SphericalPolygonsSet buildSimpleZone​(double tolerance,
                                                           double[]... points)
        Build a simple zone (connected zone without holes).

        In order to build more complex zones (not connected or with holes), the user should directly call Hipparchus SphericalPolygonsSet constructors and region factory if set operations are needed (union, intersection, difference ...).

        Take care that the vertices boundary points must be given counterclockwise. Using the wrong order defines the complementary of the real zone, and will often result in tessellation failure as the zone is too wide.

        Parameters:
        tolerance - angular separation below which points are considered equal (typically 1.0e-10)
        points - vertices of the boundary, in counterclockwise order, each point being a two-elements arrays with latitude at index 0 and longitude at index 1
        Returns:
        a zone defined on the unit 2-sphere
      • buildSimpleZone

        public static SphericalPolygonsSet buildSimpleZone​(double tolerance,
                                                           GeodeticPoint... points)
        Build a simple zone (connected zone without holes).

        In order to build more complex zones (not connected or with holes), the user should directly call Hipparchus SphericalPolygonsSet constructors and region factory if set operations are needed (union, intersection, difference ...).

        Take care that the vertices boundary points must be given counterclockwise. Using the wrong order defines the complementary of the real zone, and will often result in tessellation failure as the zone is too wide.

        Parameters:
        tolerance - angular separation below which points are considered equal (typically 1.0e-10)
        points - vertices of the boundary, in counterclockwise order
        Returns:
        a zone defined on the unit 2-sphere