Class Canvas
- All Implemented Interfaces:
Localized
- Direct Known Subclasses:
PlanarCanvas
This Canvas
base class does not draw anything by itself.
Subclasses are responsible for drawing graphic elements.
The visual contents are usually geographic located symbols, features or images,
but some implementations can also manage non-geographic elements like a map scale.
A Canvas
manages four fundamental properties:
- The coordinate reference system to use for displaying data.
- The location of data to display in all dimensions, including the dimensions not shown by the display device (for example time).
- The size of the display device, in units of the display coordinate system (typically pixels).
- The conversion from the Coordinate Reference System to the display coordinate system.
Coordinate Reference Systems
There is three Coordinate Reference Systems involved in the rendering of geospatial data:- The data CRS is specific to the data to be displayed. It may be anything convertible to the objective CRS. Different graphic elements may use different data CRS, potentially with a different number of dimensions.
- The objective CRS is the common CRS in which all data
are converted before to be displayed. If the objective CRS involves a map projection,
it determines the deformation of shapes that user will see on the display device.
The objective CRS should have the same number of dimensions than the display device
(often 2). Its domain of validity should be wide enough for encompassing all data.
The
CRS.suggestCommonTarget(…)
method may be helpful for choosing an objective CRS from a set of data CRS. - The display CRS is the coordinate system of the display device. The conversion from objective CRS to display CRS should be an affine transform with a scale, a translation and optionally a rotation. This conversion changes every time that the user zooms or scrolls on viewed data.
Location of data to display
In addition of above-cited Coordinate Reference Systems, aCanvas
also contains a point of interest.
The point of interest is often, but not necessarily, at the center of display area.
It defines the position where resolutions will be computed,
and the position to keep fixed when scales and rotations are applied.
The point of interest can be expressed in any CRS; it does not need to be the objective CRS or the CRS of any data. However, the CRS of that point must have enough dimensions for being convertible to the CRS of all data. This rule implies that the number of dimensions of the point of interest is equal or greater than the highest number of dimensions found in data. The purpose is not only to specify which point to show in (typically) the center of the display area, but also to specify which slice to select in all dimensions not shown by the display device.
Display device size
The geographic extent of data to be rendered is constrained by the zoom level and the display device size. The display size is given bygetDisplayBounds()
as an envelope having the number of dimensions of
the display device. The display bounds is usually given in pixel units, but other
units such as Units.POINT
are also authorized.
The zoom level is given indirectly by the getObjectiveToDisplay()
transform.
The display device may have a wraparound axis, for example in the spherical coordinate system of a planetarium.
Multi-threading
Canvas
is not thread-safe. Synchronization, if desired, must be done by the caller.
Another common strategy is to interact with Canvas
from a single thread,
for example the Swing or JavaFX event queue.- Since:
- 1.1
- Version:
- 1.3
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate org.opengis.referencing.crs.CoordinateReferenceSystem
TheobjectiveCRS
augmented with additional dimensions found inpointOfInterest
.private org.opengis.metadata.spatial.DimensionNameType[]
Type of each grid axis (column, row, vertical, temporal, …) ornull
if unspecified.private final DefaultCoordinateOperationFactory
The factory to use for creating coordinate operations.static final String
The "displayBounds" property name, used for notifications about changes in bounds of display device.(package private) final GeneralEnvelope
The size and location of the output device, modified in-place if the size change.private static final String
The "geographicArea" property name.private static final String
The "gridGeometry" property name.private GridGeometry
The grid geometry, computed when first needed and reset tonull
when invalidated.private final Locale
The locale for labels or error messages, ornull
for the default.private org.opengis.referencing.operation.MathTransform
The transform from the multi-dimensional CRS ofpointOfInterest
to the objective CRS.static final String
The "objectiveCRS" property name, used for notifications about changes in objective CRS.static final String
The "objectiveToDisplay" property name, used for notifications about changes in objective to display conversion.private org.opengis.referencing.crs.CoordinateReferenceSystem
The coordinate reference system in which to transform all data before displaying.private org.opengis.geometry.DirectPosition
The point of interest transformed to the objective CRS, ornull
ifpointOfInterest
has not yet been provided.private LinearTransform
The conversion from objective CRS to the display coordinate system.private final CanvasContext
The context (geographic area and desired resolution) for selecting a coordinate operation.static final String
The "pointOfInterest" property name, used for notifications about changes in point of interest.private GeneralDirectPosition
A point (in display coordinates) considered representative of the data.private static final String
The "spatialResolution" property name.private long
The dimensions in the Point Of Interest CRS that are not in theobjectiveCRS
. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription(package private) org.opengis.geometry.DirectPosition
Allocates a position which can hold a coordinates in objective CRS.private static double
Computes cos(θ)² − sin²(θ) on the given matrix row.(package private) LinearTransform
Returns the current objective to display conversion managed by the subclass.private Errors
errors()
Returns the resources bundle for error messages in the locale of this canvas.private org.opengis.referencing.operation.MathTransform
findTransform
(org.opengis.referencing.crs.CoordinateReferenceSystem source, org.opengis.referencing.crs.CoordinateReferenceSystem target, boolean allowDisplayCRS) Returns the transform from the given source CRS to the given target CRS with precedence for an operation valid for the geographic area of this canvas.private void
fireIfChanged
(String propertyName, Object oldValue, Object newValue) Fires a property change event if the old and new values are not equal.private void
fireIfChanged
(LinearTransform oldValue, LinearTransform newValue, boolean grid) Fires a property change event if the old and new transforms are not equal.(package private) void
getDisplayAxes
(org.opengis.metadata.spatial.DimensionNameType[] axisTypes) Gets the name of display axes and stores them in the given array.org.opengis.geometry.Envelope
Returns the size and location of the display device.final org.opengis.referencing.crs.EngineeringCRS
Returns the Coordinate Reference System of the display device.(package private) int
Returns the number of dimensions of the display device.Optional<org.opengis.metadata.extent.GeographicBoundingBox>
Returns the geographic bounding box encompassing the area shown on the display device.Returns canvas properties (CRS, display bounds, conversion) encapsulated in a grid geometry.Returns the locale used for texts or for producing some error messages.org.opengis.referencing.crs.CoordinateReferenceSystem
Returns the Coordinate Reference System in which all data are transformed before displaying.(package private) final double[]
Returns the coordinate values of the Point Of Interest (POI) in objective CRS.Returns the (usually affine) conversion from objective CRS to display coordinate system.org.opengis.geometry.DirectPosition
getPointOfInterest
(boolean objective) Returns the coordinates of a point considered representative of the data.Returns an estimation of the resolution (in metres) at the point of interest.private org.opengis.referencing.operation.CoordinateOperation
objectiveToGeographic
(org.opengis.referencing.crs.CoordinateReferenceSystem crs) Computes the value forobjectiveToGeographic(org.opengis.referencing.crs.CoordinateReferenceSystem)
.private static org.opengis.referencing.operation.MathTransform
orthogonalTangent
(org.opengis.referencing.operation.MathTransform newToOld, double[] poiInNew) Computes the approximate change from a newobjectiveToDisplay
to the old one for keeping the Point Of Interest (POI) at the same location.void
setDisplayBounds
(org.opengis.geometry.Envelope newValue) Sets the size and location of the display device.void
setGridGeometry
(GridGeometry newValue) Sets canvas properties from the given grid geometry.void
setObjectiveCRS
(org.opengis.referencing.crs.CoordinateReferenceSystem newValue, org.opengis.geometry.DirectPosition anchor) Sets the Coordinate Reference System in which all data are transformed before displaying.void
setObjectiveToDisplay
(LinearTransform newValue) Sets the conversion from objective CRS to display coordinate system.(package private) void
setObjectiveToDisplayImpl
(LinearTransform newValue) Actually sets the conversion from objective CRS to display coordinate system.void
setPointOfInterest
(org.opengis.geometry.DirectPosition newValue) Sets the coordinates of a representative point inside the data bounding box.Methods inherited from class org.apache.sis.portrayal.Observable
addPropertyChangeListener, firePropertyChange, firePropertyChange, hasPropertyChangeListener, removePropertyChangeListener
-
Field Details
-
OBJECTIVE_CRS_PROPERTY
The "objectiveCRS" property name, used for notifications about changes in objective CRS. The objective CRS is the Coordinate Reference System in which all data are transformed before displaying. Its number of dimension is the determined by the display device (two for flat screens). Associated values are instances ofCoordinateReferenceSystem
. -
OBJECTIVE_TO_DISPLAY_PROPERTY
The "objectiveToDisplay" property name, used for notifications about changes in objective to display conversion. This conversion maps coordinates in the objective CRS to coordinates in the display CRS. Associated values are instances ofLinearTransform
. The event class is theTransformChangeEvent
specialization. -
DISPLAY_BOUNDS_PROPERTY
The "displayBounds" property name, used for notifications about changes in bounds of display device. It may be for example changes in the size of the window were data are shown. Associated values are instances ofEnvelope
. -
POINT_OF_INTEREST_PROPERTY
The "pointOfInterest" property name, used for notifications about changes in point of interest. The point of interest defines the location of a representative point, typically (but not necessarily) in the center of the data bounding box. It defines also the slice coordinate values in all dimensions beyond the ones shown by the device. Associated values are instances ofDirectPosition
. -
GRID_GEOMETRY_PROPERTY
The "gridGeometry" property name. The grid geometry is a synthetic property computed from other properties when requested. The computed grid geometry may change every time that a "objectiveCRS", "objectiveToDisplay", "displayBounds" or "pointOfInterest" property is changed. We do not (at this time) fire "gridGeometry" change events because computing a new grid geometry for every changes of above-cited properties would be costly. An alternative approach could be to fire "gridGeometry" event only whensetGridGeometry(GridGeometry)
is explicitly invoked, but it could be misleading if it gives the false impression that the grid geometry did not changed because a listener did not received an "gridGeometry" event. -
GEOGRAPHIC_AREA_PROPERTY
The "geographicArea" property name. The geographic area is a synthetic property computed from "displayBounds", "objectiveToDisplay" and "objectiveCRS". There are no events fired for this property.- See Also:
-
SPATIAL_RESOLUTION_PROPERTY
The "spatialResolution" property name. The resolution is a synthetic property computed from "pointOfInterest", "objectiveToDisplay" and "objectiveCRS". There are no events fired for this property.- See Also:
-
objectiveCRS
private org.opengis.referencing.crs.CoordinateReferenceSystem objectiveCRSThe coordinate reference system in which to transform all data before displaying. Ifnull
, then no transformation is applied and data coordinates are used directly as display coordinates, regardless the data CRS (even if different data use different CRS). -
objectiveToDisplay
The conversion from objective CRS to the display coordinate system. Conceptually this conversion should never be null (its initial value is the identity conversion). However, subclasses may use a more specialized type such asAffineTransform
and set this field tonull
for recomputing it from the specialized type when requested. -
displayBounds
The size and location of the output device, modified in-place if the size change. The CRS of this envelope is the display CRS. Coordinate values are initially NaN. -
pointOfInterest
A point (in display coordinates) considered representative of the data. This is the default location where Jacobian matrices are computed when needed. This is typically (but not necessarily) the center of data bounding box. May become outside the viewing area after zooms or translations have been applied. Also used for selecting a slice in all supplemental dimensions. Ifnull
, then calculations that depend on a point of interest are skipped. -
objectivePOI
private org.opengis.geometry.DirectPosition objectivePOIThe point of interest transformed to the objective CRS, ornull
ifpointOfInterest
has not yet been provided. This point shall be updated immediately whenpointOfInterest
is updated, as a way to verify that the point is valid.There is no setter method for this property. It is computed from
pointOfInterest
andobjectiveCRS
(indirectly, throughmultidimToObjective
) and should be recomputed when any of those properties changed.- See Also:
-
multidimToObjective
private org.opengis.referencing.operation.MathTransform multidimToObjectiveThe transform from the multi-dimensional CRS ofpointOfInterest
to the objective CRS. This is the transform used for computingobjectivePOI
. This transform may reduce the number of dimensions.There is no setter method for this property. It is computed from
pointOfInterest
andobjectiveCRS
and should be recomputed when any of those properties changed.In current implementation, this transform may depend on the zoom level and viewed geographic area at the time this transform has been computed. The transform could be slightly different if it has been computed at the time a different geographic area was viewed. Those variations may exist because
findTransform(CoordinateReferenceSystem, CoordinateReferenceSystem, boolean)
takes in account the current viewing conditions. We may need to revisit this behavior in the future if it appears to be a problem.- See Also:
-
augmentedObjectiveCRS
private org.opengis.referencing.crs.CoordinateReferenceSystem augmentedObjectiveCRSTheobjectiveCRS
augmented with additional dimensions found inpointOfInterest
. This field is initiallynull
and computed only if needed. It may be reset tonull
at any time if the properties used for computing this value changed.If the point of interest has no supplemental dimension, then this CRS is
objectiveCRS
. Otherwise supplemental dimensions are added on a best effort basis: some supplemental dimensions may be missing if we have not been able to separate components from the Point Of Interest CRS.- See Also:
-
supplementalDimensions
private long supplementalDimensionsThe dimensions in the Point Of Interest CRS that are not in theobjectiveCRS
. Those dimensions are encoded as a bitmask: if dimension n is a supplemental dimension, then the bit1L << n
is set to 1. This encoding implies that we can not handle more than 64 dimensions at this time.The value of this field is invalid if
augmentedObjectiveCRS
isnull
. Those two fields are computed together.- See Also:
-
axisTypes
private org.opengis.metadata.spatial.DimensionNameType[] axisTypesType of each grid axis (column, row, vertical, temporal, …) ornull
if unspecified. This is only a help for debugging purpose, by providing more information to the developers. Those types should not be used for any "real" work.- See Also:
-
gridGeometry
The grid geometry, computed when first needed and reset tonull
when invalidated. This is invalidated when anyCanvas
property is modified. In particular, this is invalidated every time that theobjectiveToDisplay
transform changes. Note that "objective to display" changes happen much more often than changes in other properties.The
augmentedObjectiveCRS
,supplementalDimensions
,multidimToObjective
,objectivePOI
andaxisTypes
objects are intermediate calculations with typically a longer lifetime thangridGeometry
. They are saved for faster recomputation of grid geometry when only theobjectiveToDisplay
transform has changed. -
operationContext
The context (geographic area and desired resolution) for selecting a coordinate operation. The information contained in this object can opportunistically be used for providing the geographic area and spatial resolution of this canvas. -
coordinateOperationFactory
The factory to use for creating coordinate operations. This factory allow us to specify the area of interest (the geographic region shown by thisCanvas
) and the desired resolution. -
locale
The locale for labels or error messages, ornull
for the default.
-
-
Constructor Details
-
Canvas
Creates a new canvas for a display device using the given coordinate reference system. The display CRS of a canvas cannot be changed after construction. Its coordinate system depends on the display device shape (for example a two-dimensional Cartesian coordinate system for flat screens, or a polar or spherical coordinate system for planetarium domes). The axis units of measurement are typically (but not necessarily)Units.PIXEL
for Cartesian coordinate systems, withUnits.DEGREE
in polar, cylindrical or spherical coordinate systems.- Parameters:
displayCRS
- the coordinate system of the display device.locale
- the locale to use for labels and some messages, ornull
for default.
-
-
Method Details
-
getLocale
Returns the locale used for texts or for producing some error messages. May benull
if no locale has been specified, in which case the system default should be used. -
getDisplayDimensions
int getDisplayDimensions()Returns the number of dimensions of the display device. Subclasses may override for a little bit more efficiency. -
getDisplayAxes
void getDisplayAxes(org.opengis.metadata.spatial.DimensionNameType[] axisTypes) Gets the name of display axes and stores them in the given array. Those display axis names are used for debugging purposes only, as an additional information provided to developers. Those names should not be used for any "real" work. The default implementation does nothing since this baseCanvas
class does not know well the geometry of the display device. It is okay to leave elements tonull
.- Parameters:
axisTypes
- where to store the name of display axes. The array length will be at leastgetDisplayDimensions()
(it will often be longer).
-
getDisplayCRS
public final org.opengis.referencing.crs.EngineeringCRS getDisplayCRS()Returns the Coordinate Reference System of the display device. The axis units of measurement are typically (but not necessarily)Units.PIXEL
for Cartesian coordinate systems, withUnits.DEGREE
in polar, cylindrical or spherical coordinate systems. The coordinate system may have a wraparound axis for some "exotic" display devices (e.g. planetarium dome).Usage note: invoking this method is rarely needed. It is sufficient to said that a display CRS exists at least conceptually, and that we define a conversion from the objective CRS to that display CRS. This method may be useful when the subclasses may be something else thanPlanarCanvas
, in which case the caller may want more information about the geometry of the display device.Note that the
CRS.findOperation(…)
static method can generally not handle this display CRS. To apply coordinate operations on display coordinates,getObjectiveToDisplay()
transform must be inverted and used.- Returns:
- the Coordinate Reference System of the display device.
- See Also:
-
getObjectiveCRS
public org.opengis.referencing.crs.CoordinateReferenceSystem getObjectiveCRS()Returns the Coordinate Reference System in which all data are transformed before displaying. After conversion to this CRS, coordinates should be related to the display device coordinates with only a final scale, a translation and optionally a rotation remaining to apply.This value may be
null
on newly createdCanvas
, before data are added and canvas is configured. It should not benull
anymore once aCanvas
is ready for displaying.- Returns:
- the Coordinate Reference System in which to transform all data before displaying.
- See Also:
-
setObjectiveCRS
public void setObjectiveCRS(org.opengis.referencing.crs.CoordinateReferenceSystem newValue, org.opengis.geometry.DirectPosition anchor) throws RenderException Sets the Coordinate Reference System in which all data are transformed before displaying. The new CRS must be compatible with the previous CRS, i.e. a coordinate operation between the two CRSs shall exist. If this is not the case (e.g. for rendering completely new data), usesetGridGeometry(GridGeometry)
instead.The given CRS should have a domain of validity wide enough for encompassing all data (the
CRS.suggestCommonTarget(…)
method may be helpful for choosing an objective CRS from a set of data CRS). If the given value is different than the previous value, then a change event is sent to all listeners registered for the "objectiveCRS" property.If the transform between old and new CRS is not identity, then this method recomputes the objective to display conversion in a way preserving the display coordinates of the given anchor, together with the scales and orientations of features in close neighborhood of that point. This calculation may cause "objectiveToDisplay" property change event with the
TransformChangeEvent.Reason.CRS_CHANGE
reason to be sent to listeners. That event is sent after the above-cited "objectiveCRS" event (note that "pointOfInterest" stay unchanged). All those change events are sent only after all property values have been updated to their new values.- Parameters:
newValue
- the new Coordinate Reference System in which to transform all data before displaying.anchor
- the point to keep at fixed display coordinates, expressed in any compatible CRS. Ifnull
, defaults to point of interest. If non-null, the anchor must be associated to a CRS.- Throws:
NullPointerException
- if the given CRS is null.org.opengis.geometry.MismatchedDimensionException
- if the given CRS does not have the number of dimensions of the display device.RenderException
- if the objective CRS cannot be set to the given value for another reason.
-
orthogonalTangent
private static org.opengis.referencing.operation.MathTransform orthogonalTangent(org.opengis.referencing.operation.MathTransform newToOld, double[] poiInNew) throws org.opengis.referencing.operation.TransformException, RenderException Computes the approximate change from a newobjectiveToDisplay
to the old one for keeping the Point Of Interest (POI) at the same location. The givennewToOld
argument is the change as a potentially non-linear transform. The transform returned by this method is a linear approximation ofnewToOld
tangent at the POI, but with orthogonal vectors. In other words, the returned transform may apply a uniform scale, a rotation or flip axes, but no shear.- Parameters:
newToOld
- the change as a potentially non-linear transform.poiInNew
- point of interest in the coordinates of the new objective CRS.- Returns:
- an approximation of
newToOld
with only uniform scale, rotation and axis flips. - Throws:
org.opengis.referencing.operation.TransformException
RenderException
- See Also:
-
cps
Computes cos(θ)² − sin²(θ) on the given matrix row. Caller needs to add 1 for getting the sum of squares of cosine values. That addition should be done last for reducing rounding errors. -
getObjectiveToDisplay
Returns the (usually affine) conversion from objective CRS to display coordinate system. The source coordinates shall be in the CRS given bygetObjectiveCRS()
and the converted coordinates will be in the CRS given bygetDisplayCRS()
.The objective to display conversion changes every time that user zooms or scrolls on viewed data. However, the transform returned by this method is a snapshot taken at the time this method is invoked; subsequent changes in the objective to display conversion are not reflected in the returned transform.
- Returns:
- snapshot of the (usually affine) conversion from objective CRS
to display coordinate system (never
null
). - See Also:
-
createObjectiveToDisplay
LinearTransform createObjectiveToDisplay()Returns the current objective to display conversion managed by the subclass. This method is invoked only ifobjectiveToDisplay
isnull
, which may happen either at initialization time or if the subclass uses its own specialized field instead ofobjectiveToDisplay
for managing changes in the zooms or viewed area. This method needs to be overridden only by subclasses using such specialization.- Returns:
- objective to display conversion created from current value managed by subclass.
- See Also:
-
setObjectiveToDisplay
Sets the conversion from objective CRS to display coordinate system. If the given value is different than the previous value, then a change event is sent to all listeners registered for the "objectiveToDisplay" property. The event reason isTransformChangeEvent.Reason.ASSIGNMENT
.Invoking this method has the effect of changing the viewed area, the zoom level or the rotation of the map. It does not update the "pointOfInterest" property however. The point of interest may move outside the view area as a result of this method call.
- Parameters:
newValue
- the new objective to display conversion.- Throws:
IllegalArgumentException
- if given the transform does not have the expected number of dimensions or is not affine.RenderException
- if the objective to display transform cannot be set to the given value for another reason.
-
setObjectiveToDisplayImpl
Actually sets the conversion from objective CRS to display coordinate system. Contrarily to other setter methods, this method does not notify listeners about that change; it is caller responsibility to fire aTransformChangeEvent
after all fields are updated. This design choice is because this method is usually invoked as part of a larger set of changes.If the new value is
null
, then this method only declares that theobjectiveToDisplay
transform became invalid and will need to be recomputed. It is subclasses responsibility to recompute the transform in theircreateObjectiveToDisplay()
.- Parameters:
newValue
- the new "objective to display" transform, ornull
if it will be computed later bycreateObjectiveToDisplay()
. A null value is okay only when invoked by subclasses that overrodecreateObjectiveToDisplay()
.- See Also:
-
getDisplayBounds
public org.opengis.geometry.Envelope getDisplayBounds()Returns the size and location of the display device. The unit of measurement is typically (but not necessarily) pixels. The coordinate values are often integers, but this is not mandatory. The coordinate reference system is given bygetDisplayCRS()
.This value may be
null
on newly createdCanvas
, before data are added and canvas is configured. It should not benull
anymore once aCanvas
is ready for displaying.- Returns:
- size and location of the display device.
- See Also:
-
setDisplayBounds
Sets the size and location of the display device. The envelope CRS shall be either the display CRS or unspecified, in which case the display CRS is assumed. Unit of measurement is typically (but not necessarily)Units.PIXEL
. If the given value is different than the previous value, then a change event is sent to all listeners registered for the "displayBounds" property.- Parameters:
newValue
- the new display bounds.- Throws:
IllegalArgumentException
- if the given envelope does not have the expected CRS or number of dimensions.RenderException
- if the display bounds cannot be set to the given value for another reason.
-
getPointOfInterest
public org.opengis.geometry.DirectPosition getPointOfInterest(boolean objective) Returns the coordinates of a point considered representative of the data. This is typically (but not necessarily) the center of data bounding box. This point is used for example as the default location where to compute resolution (the resolution may vary at each pixel because of map projection deformations). This position may become outside the viewing area after zooms or translations have been applied.The coordinates can be given in their original CRS or in the objective CRS. If
objective
isfalse
, then the returned position can be expressed in any CRS convertible to data or objective CRS. If that CRS has more dimensions than the objective CRS, then the supplemental dimensions specify which slice to show (for example the depth of the horizontal plane to display, or the date of the dynamic phenomenon to display. See class javadoc for more discussion.) Ifobjective
istrue
, then the position is transformed to the objective CRS.This value is initially
null
. A value should be specified either by invokingsetPointOfInterest(DirectPosition)
orsetGridGeometry(GridGeometry)
.- Parameters:
objective
- whether to return a position transformed to objective CRS.- Returns:
- coordinates of a representative point, or
null
if unspecified. - See Also:
-
setPointOfInterest
Sets the coordinates of a representative point inside the data bounding box. If the given value is different than the previous value, then a change event is sent to all listeners registered for the "pointOfInterest" property.- Parameters:
newValue
- the new coordinates of a representative point.- Throws:
NullPointerException
- if the given position is null.IllegalArgumentException
- if the given position does not have a CRS.RenderException
- if the point of interest cannot be set to the given value.
-
getObjectivePOI
final double[] getObjectivePOI()Returns the coordinate values of the Point Of Interest (POI) in objective CRS. The array length should be equal togetDisplayDimensions()
. May benull
if the point of interest is unknown. -
getGridGeometry
Returns canvas properties (CRS, display bounds, conversion) encapsulated in a grid geometry. This is a convenience method for interoperability with grid coverage API. IfsetGridGeometry(GridGeometry)
has been invoked with a non-null value and no otherCanvas
property changed since that method call, then this method returns that value. Otherwise this method computes a grid geometry as described below.The set of
GridGeometry
dimensions includes all the dimensions of the objective CRS, augmented with all (if possible) or some supplemental dimensions found in the point of interest. For example if the canvas manages only (x,y) coordinates but the point of interest includes also a t coordinate, then a third dimension (which we call the supplemental dimension) for t is added to the CRS,GridExtent
and "grid to CRS" transform of the returned grid geometry.Canvas properties → grid geometry properties Grid geometry element Display dimensions Supplemental dimensions GridGeometry.getCoordinateReferenceSystem()
getObjectiveCRS()
.Some of getPointOfInterest(false).getCoordinateReferenceSystem()
GridGeometry.getExtent()
getDisplayBounds()
rounded to enclosing (floor and ceil) integers[0 … 0] GridGeometry.getGridToCRS(PixelInCell)
Inverse of getObjectiveToDisplay()
Some point of interest coordinates as translation terms GridGeometry.getGridToCRS(PixelInCell)
transform built by this method is always aLinearTransform
. This linearity implies that the grid geometry CRS cannot be the Point Of Interest (POI) CRS, unless conversion from POI CRS to objective CRS is linear.- Returns:
- a grid geometry encapsulating canvas properties, including supplemental dimensions if possible.
- Throws:
RenderException
- if the grid geometry cannot be computed.
-
setGridGeometry
Sets canvas properties from the given grid geometry. This convenience method converts the coordinate reference system, "grid to CRS" transform and extent of the given grid geometry toCanvas
properties. If the given value is different than the previous value, then change events are sent to all listeners registered for the "displayBounds", "objectiveCRS", "objectiveToDisplay" (withTransformChangeEvent.Reason.GRID_GEOMETRY_CHANGE
reason), and/or "pointOfInterest" properties, in that order.The value given to this method will be returned by
getGridGeometry()
as long as none of above cited properties is changed. If one of those properties changes (for example if the user zooms or pans the map), then a new grid geometry will be computed. There is no guarantee that the recomputed grid geometry will be similar to the grid geometry specified to this method. For example, theGridExtent
in supplemental dimensions may be different.- Parameters:
newValue
- the grid geometry from which to get new canvas properties.- Throws:
RenderException
- if the given grid geometry cannot be converted to canvas properties.
-
fireIfChanged
Fires a property change event if the old and new values are not equal.- Parameters:
propertyName
- name of the property that changed its value.oldValue
- the old property value (may benull
).newValue
- the new property value.
-
fireIfChanged
Fires a property change event if the old and new transforms are not equal.- Parameters:
oldValue
- the old "objective to display" transform.newValue
- the new transform, ornull
for lazy computation.grid
-true
if the reason is a grid geometry change, orfalse
if only a CRS change.
-
getGeographicArea
public Optional<org.opengis.metadata.extent.GeographicBoundingBox> getGeographicArea() throws RenderExceptionReturns the geographic bounding box encompassing the area shown on the display device. If the objective CRS is not convertible to a geographic CRS, then this method returns an empty value.- Returns:
- geographic bounding box encompassing the viewed area.
- Throws:
RenderException
- in an error occurred while computing the geographic area.- See Also:
-
getSpatialResolution
Returns an estimation of the resolution (in metres) at the point of interest. If the objective CRS is not convertible to a geographic CRS, then this method returns an empty value.- Returns:
- estimation of the resolution in metres at current point of interest.
- Throws:
RenderException
- in an error occurred while computing the resolution.
-
objectiveToGeographic
private org.opengis.referencing.operation.CoordinateOperation objectiveToGeographic(org.opengis.referencing.crs.CoordinateReferenceSystem crs) throws org.opengis.util.FactoryException Computes the value forobjectiveToGeographic(org.opengis.referencing.crs.CoordinateReferenceSystem)
. The value is not stored by this method for giving caller a chance to validate other properties before to write them in a "all or nothing" way.- Parameters:
crs
- the new objective CRS in process of being set by the caller.- Returns:
- the conversion from given CRS to geographic CRS, or
null
if none. - Throws:
org.opengis.util.FactoryException
-
findTransform
private org.opengis.referencing.operation.MathTransform findTransform(org.opengis.referencing.crs.CoordinateReferenceSystem source, org.opengis.referencing.crs.CoordinateReferenceSystem target, boolean allowDisplayCRS) throws org.opengis.util.FactoryException, org.opengis.referencing.operation.TransformException, RenderException Returns the transform from the given source CRS to the given target CRS with precedence for an operation valid for the geographic area of this canvas. The transform returned by this method for the same pair of CRS may differ depending on which area is currently visible in the canvas. All requests for a coordinate operation should invoke this method instead ofCRS.findOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, GeographicBoundingBox)
.- Parameters:
allowDisplayCRS
- whether thesourceCRS
can begetDisplayCRS()
.- Throws:
org.opengis.util.FactoryException
org.opengis.referencing.operation.TransformException
RenderException
-
allocatePosition
org.opengis.geometry.DirectPosition allocatePosition()Allocates a position which can hold a coordinates in objective CRS. May be overridden by subclasses for a little bit more efficiency. -
errors
Returns the resources bundle for error messages in the locale of this canvas.
-