Better documentation and testing regarding how shapes which cross the dateline are handled

[chrisbennight]

Need to document this (preferably with some nice graphics) - since it's an area of confusion.

We also need to add in some test cases that explicitly check for this to make sure our documentation matches what is happening.

[chrisbennight]

Specs on how latitudes greater than 90 / less than -90 and longitudes which cross the dateline should be handled.

• Latitudes
  • epsilon is a factor to handle fuzzy precision of floating point values. I think we use 1E-12 in other places.
  • Latitudes values outside the range of (-90 - epsilon) and (90 + epsilon) will not be accepted in geowave indexing (exception will be thrown - we don't want to ingest/store values we consider out of spec)
  • These values can be handled prior to indexing if a particular data set has a convention on using them / what they mean. (see below for handling (i.e. outside of geowave-index))
• Longitudes
  • Longitude values outside the range of (-180 -epsilon) and (180 + epsilon) will not be accepted in geowave indexing (exception will be thrown)
  • Values outside the range (dateline crossing, etc.) will be handled outside of geowave-index (see below for handling)
• Handling
  • Two places have been identified that need to implement the "outside the cartesian plane" handling described above. More may be identified at a later date, and should implement the same logic.
    • Query: Query ranges, geometries, etc. which include values outside of the cartesian plane will need to be "normalized" to being within the cartesian plane.
    • Ingest: Geometries being ingested which contain values outside the cartesian plane will need to be decomposed as well.
  • Geometries which cross the date line will be broken down into a multi-geometry (of the appropriate type), and stored at multiple index locations (with the serialized value being the full multi-geometry).
  • The number of times that the cartesian plane is "wrapped" (i.e. -500 to +500) is not relevant; we just need to define the portion of the plane intersected by the query (one or 100 "wrappings", for instance, would effectively become -180 to +180)
  • ToDo: Generate Graphic

[rfecher]

we always assume that latitude is clamped to -90, 90 and longitude follows so:

        final double offsetLon = lon + 180;
        return (((Math.ceil(Math.abs(offsetLon) / 360) * 360) + offsetLon) % 360) - 180;