Envelope

Envelopes

Envelopes store minimal and maximal coordinate values of a geometry. Envelopes are not geometries themselves; they are not infinite sets of points (TransfiniteSet). There is no guarantee that all the positions contained within the limits of an envelope are geographically valid. Envelopes must be seen as information about extreme values that might take the coordinates of a geometry as if each dimension were independent of the others, nothing more. Nevertheless, we speak of envelopes as rectangles, cubes or hyper-cubes (depending on the number of dimensions) in order to facilitate discussion, while bearing in mind their non-geometric nature.

Example: We could test whether a position is within the limits of an envelope. A positive result does not guarantee that the position is within the geometry delimited by the envelope, but a negative result guarantees that it is outside the geometry. We can perform intersection tests in the same way. On the other hand, it makes little sense to apply a rotation to an envelope, as the result may be very different from that which we would obtain by performing a rotation on the original geometry, and then recalculating its envelope.

An envelope might be represented by two positions corresponding to two opposite corners of a rectangle, cube or hyper-cube. For the first corner, we often take the one whose ordinates all have the maximal value (upperCorner). When displayed using a conventional system of coordinates (with y axis values running upwards), these two positions appear respectively in the lower left corner and the upper right corner of a rectangle. Care must be taken with different coordinate systems, however, which may vary the positions of these corners on the screen. The expressions lower corner and upper corner should thus be understood in the mathematical rather than the visual sense.

Crossing the antimeridian

Minimums and maximums are the values most often assigned to lowerCorner and upperCorner. But the situation becomes complicated when an envelope crosses the antimeridian (−180° or 180° longitude). For example, an envelope 10° in size may begin at 175° longitude and end at −175°. In this case, the longitude value assigned to lowerCorner is greater than that assigned to upperCorner. Apache SIS therefore uses a slightly different definition of these two corners:

lowerCorner: the starting point, if we move along the inside of the envelope in the direction of ascending values.
upperCorner: the end-point, if we move along the inside of the envelope in the direction of ascending values.

If the envelope does not cross the antimeridian, these two definitions are equivalent to the selection of minimal and maximal values respectively. This is the case in the green rectangle in the figure below. When the envelope crosses the antimeridian, the lowerCorner and the upperCorner appear again at the bottom and top of the rectangle (assuming a standard system of coordinates), so their names remain appropriate from a visual standpoint. However, the left and right positions are switched. This case is illustrated by the red rectangle in the figure below.

Envelope example with and without anti-meridian spanning.

The notions of inclusion and intersection, however, are interpreted slightly differently in these two cases. In the usual case where the envelope does not cross the antimeridian, the green rectangle covers a region of inclusion. The regions excluded from this rectangle continue on to infinity in all directions. In other words, the region of inclusion is not repeated every 360°. But in the case of the red rectangle, the information provided by the envelope actually covers a region of exclusion between the two edges of the rectangle. The region of inclusion extends to infinity to the left and right. We could stipulate that all longitudes below −180° or above 180° are considered excluded, but this would be an arbitrary decision that would not be an exact counterpart to the usual case (green rectangle). A developer may wish to use these values, for example, in a mosaic where the map of the world is repeated several times horizontally and each repetition is considered distinct. If developers wish to perform operations as though the regions of inclusion or exclusion were repeated every 360°, they themselves will have to bring the longitudinal values between −180° and 180° in advance. All the add(…), contains(…), intersect(…), etc. functions of all the envelopes defined in the org.apache.sis.geometry package perform their calculations according to this convention.

Generalizing to other types of axes

This section specifically relates to longitude, as it is the most usual example of a cyclic axis. However, in Apache SIS envelopes, there is no explicit mention of longitude, or of its 360° cycle. The characteristics of the range of values of each axis (its extremum, units, type of cycle, etc.) are attributes of CoordinateSystemAxis objects, indirectly associated with envelopes via the coordinate reference system. Apache SIS inspects these attributes to determine the way in which it must perform these operations. Thus, any axis associated with the code RangeMeaning.WRAPAROUND benefit from the same treatment as does longitude. For example, this could be a time axis for climatological data (one “year” represents the average temperature in all the months of January, followed by the average of all the months of February, etc.) This generalization also applies to longitude axes defined by a range of 0° to 360° rather than −180° to 180°.

In order for functions such as add(…) to work correctly, all objects involved must use the same coordinate reference system, including the same range of values. Thus an envelope that expresses longitudes in the range [−180 … +180]° is not compatible with an envelope that expresses longitudes in the range [0 … 360]°. The conversions, if necessary, are up to the user (the Envelopes class provides convenience methods to do this). Moreover, the envelope’s coordinates must be included within the system of coordinates, unless the developer explicitly decides to consider (for example) 300° longitude as a position distinct from −60°. The GeneralEnvelope class provides a normalize() method to bring coordinates within the desired limits, sometimes at the cost of lower values being higher than upper values.

The special case of [+0 … −0] range

Java (or more generally, IEEE Standard 754) defines two zero values: a positive zero and a negative zero. These two values are considered equal when we compare them with the == operator in Java. But in SIS envelopes, they may actually return opposite results for axes using RangeMeaning.WRAPAROUND. An envelope whose range is [0 … 0], [−0 … −0] or [−0 … +0] would normally be considered an empty envelope, but the [+0 … −0] range would in fact be considered to include the entire set of values all around the world. This behaviour conforms to the definition of lowerCorner and upperCorner, which considers +0 as the starting point, and −0 as the end-point after cycling through all possible values. Such behaviour only occurs for the pair of values +0 and −0, and only in that order. For all other real values, if the condition lower == upper is true, then it is guaranteed that the envelope is empty.

Transforming to another reference system

Geographic information systems often need to transform an envelope from one Coordinate Reference System (CRS) to another. But a naive approach transforming the 4 corners is not sufficient. The figure below shows an envelope before a map projection and the geometric shape that we would get if all points (not only the corners) were projected. The resulting geometric shape is more complex than a rectangle because of the curvature caused by the map projection. Computing the envelope that contains the 4 corners of that shape is not enough, because the area in the bottom of the projected shape is lower than the two bottom corners. That surface would be outside the envelope.

Envelope before projection

Geometric shape after projection

Sampling a larger number of points reduces the problem but does not resolve it. Map projection derivatives offer a more efficient way to resolve this problem (see the annex for more mathematical details). Another complication occurs if the envelope contains the North or South pole. For making a long story short, transforming an envelope is a lot more complicated than it looks like. Apache SIS contains a few utility methods for making this task easier. For transforming an envelope to another CRS (WGS 84 / World Mercator in this example):

CoordinateReferenceSystem targetCRS = CRS.forCode("EPSG:3395");
Envelope transformed = Envelopes.transform(envelope, targetCRS);

If envelopes are transformed in the goal of using a common CRS before to compute the union of many envelopes, an additional complication is that each envelope may use a CRS with a relatively small domain of validity. The union operation needs to find a CRS valid in a domain large enough for containing all envelopes. It may be a CRS different than all CRS used by the source envelopes. Apache SIS has an utility method for handling this additional complexity. This method accepts an arbitrary number of envelopes that may be in different CRS:

Envelope union = Envelopes.union(envelope1, envelope2, envelope3);