001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2013 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.display.canvas;
033
034 import org.opengis.geometry.DirectPosition;
035 import org.opengis.referencing.cs.CartesianCS;
036 import org.opengis.referencing.cs.SphericalCS;
037 import org.opengis.referencing.crs.DerivedCRS;
038 import org.opengis.referencing.crs.ProjectedCRS;
039 import org.opengis.referencing.crs.CoordinateReferenceSystem;
040 import org.opengis.referencing.operation.MathTransform;
041 import org.opengis.util.InternationalString;
042
043
044 /**
045 * Describe the current state of a {@linkplain Canvas canvas}. The information contained
046 * by instances of this interface should only describe the viewing area or volume of the
047 * canvas and should not contain any state information regarding the data contained within it.
048 * <p>
049 * When an instance of this class is returned from {@code Canvas} methods, a "snapshot"
050 * of the current state of the canvas is taken and the values will never change (even
051 * if the canvas changes state).
052 *
053 * @author Open Geospatial Consortium
054 * @author Johann Sorel (Geomatys)
055 * @since GeoAPI 2.2
056 */
057 public interface CanvasState {
058 /**
059 * Returns the title of the {@linkplain Canvas canvas}.
060 *
061 * @return The canvas title.
062 *
063 * @see CanvasController#setTitle
064 */
065 InternationalString getTitle();
066
067 /**
068 * Returns the position of the center point of the {@linkplain Canvas canvas}.
069 * The coordinate shall be in {@linkplain #getObjectiveCRS objective CRS}.
070 *
071 * @return The center point in objective CRS.
072 *
073 * @see CanvasController#setCenter
074 */
075 DirectPosition getCenter();
076
077 /**
078 * Returns the "real world" Coordinate Reference System. This is typically
079 * a {@linkplain ProjectedCRS projected CRS} using linear units like metre.
080 * Graphic data are projected to this CRS before to be display.
081 *
082 * @return The "real world" Coordinate Reference System.
083 *
084 * @see CanvasController#setObjectiveCRS
085 */
086 CoordinateReferenceSystem getObjectiveCRS();
087
088 /**
089 * Returns the Coordinate Reference System associated with the
090 * display of the {@linkplain Canvas canvas}. The display CRS
091 * {@linkplain CoordinateReferenceSystem#getCoordinateSystem has a Coordinate System}
092 * corresponding to the geometry of the display device. For example flat video monitors
093 * are associated to {@linkplain CartesianCS cartesian CS} while planetarium may be
094 * associated to {@linkplain SphericalCS spherical CS}. Axis units are typically (but
095 * are not restricted to) some linear units like 1/72 of inch.
096 * <p>
097 * This CRS can be implemented as a {@linkplain DerivedCRS derived CRS} based on the
098 * {@linkplain #getObjectiveCRS objective CRS}. In such implementations, the display
099 * CRS changes after every zoom or translation action.
100 *
101 * @return The display Coordinate Reference System.
102 */
103 CoordinateReferenceSystem getDisplayCRS();
104
105 /**
106 * Returns the transform from {@linkplain #getObjectiveCRS objective} to
107 * {@linkplain #getDisplayCRS display} CRS. If the later is implemented as
108 * a {@linkplain DerivedCRS derived CRS}, then this transform shall be equal
109 * to the following:
110 *
111 * <blockquote><code>
112 * getDisplayCRS().{@linkplain DerivedCRS#getConversionFromBase getConversionFromBase()}.getMathTransform()
113 * </code></blockquote>
114 *
115 * This transform is typically (but is not required to be) affine. When this transform is
116 * affine, then the scale factors (the coefficients on the matrix diagonal when there is
117 * no rotation or shear) are the map scale along the corresponding axis.
118 *
119 * @return The transform from {@linkplain #getObjectiveCRS objective} to
120 * {@linkplain #getDisplayCRS display} CRS.
121 */
122 MathTransform getObjectiveToDisplayTransform();
123
124 /**
125 * Returns the transform from {@linkplain #getDisplayCRS display}
126 * to {@linkplain #getObjectiveCRS objective} CRS. This is the
127 * {@linkplain MathTransform#inverse inverse} of the
128 * {@linkplain #getObjectiveToDisplayTransform objective to display transform}.
129 *
130 * @return The transform from {@linkplain #getDisplayCRS display} to
131 * {@linkplain #getObjectiveCRS objective} CRS.
132 */
133 MathTransform getDisplayToObjectiveTransform();
134 }