[[TOC]] = Index CRSs This page describes how to use and interpret Index Coordinate Reference Systems (CRSs): how they differ from other linear coordinate systems and especially how they differ from the ''internal'' grid CRS, known as `CRS:1`. GML definitions for [http://rasdaman.org:8080/def/crs/OGC/0/Index1D Index1D], [http://rasdaman.org:8080/def/crs/OGC/0/Index2D Index2D] and [http://rasdaman.org:8080/def/crs/OGC/0/Index3D Index3D] are already embedded in our [SecoreDevGuide SECORE] resolver and their official acknowledgment is on OGC table. == Definition As you can verify by looking at the "extra" (non-EPSG) CRS definitions [http://rasdaman.org:8080/def/crs/OGC/0/ provided] by SECORE, among others there are three new Index CRSs, namely [http://rasdaman.org:8080/def/crs/OGC/0/Index1D 1D], [http://rasdaman.org:8080/def/crs/OGC/0/Index2D 2D] and [http://rasdaman.org:8080/def/crs/OGC/0/Index3D 3D] reference systems. The ''index'' prefix refers to the fact that ''integral'' coordinates shall be used in the coordinates. The n-dimensional (cartesian) Coordinate System (CS) is supposed to be bound to a multidimensional array (marray) of cells: the origin of the CS is placed in the centre of the 0-cell. This represents the ''datum'', and completes the picture to define the CRS. [[Image(indexCrs.png, center, 70%)]] Using index CRSs can be useful especially when using `rasdaman` for applications not related to the geo-referenced world of satellite products, or more generally to remote-sensing imagery. For instance, `rasdaman` could be used to process [http://link.springer.com/article/10.1134/S105466181304007X large bio-medical images], which do not need a geo-reference. The previous case is out of scope in the OGC services, and it is probably better handled via direct `rasql` requests (also via [PetascopeUserGuide Petascope] `rasql` web interface). However, more interestingly, index CRSs could also be used to access "pixel" coordinates from a geoimage, or to access layers of height/time via their ordinal position in the stack (this requires CRS extensions [wiki:Features available]). Index CRSs exploit indexed cartesian CSs by defining the Unit of Measure (Uom) of each of its axes to be an integral. The specific terminology that is used is [http://www.opengis.net/def/uom/OGC/1.0/GridSpacing GridSpacing], defined by OGC in the context of the [http://www.opengeospatial.org/standards/deprecated deprecated] (2D) Image CRS. Indeed index CRSs are considered the n-dimensional extension/generalization of the previously defined [http://schemas.opengis.net/ImageCRSs/ Image CRSs]: this means replacing the typically-2D terminology of ''pixels'', ''rows'' and ''columns'' with the more general ''cells'' and ''axis'' terms. The following picture clarifies what is the space of coordinates covered by a standard 2D (linear) cartesian CS, and an indexed one: [[Image(IndexVsCartesianCRS.png, center, 90%)]] The 2D space is fully covered on a geometric space with no additional constraints, whereas limiting the coordinates to integrals confines the address space to a grid of 0D points. While this can be easily understandable, it has some important consequences: '''sample sizes''' (footprints) of a coverage's points are confined to be 0D on an index CRSs since the areas between CRS points are not reachable by the indexed coordinates. In the regular 2D case a pixel usually represents its extent/area (though [http://trac.osgeo.org/gdal/wiki/rfc33_gtiff_pixelispoint not always] of course), while a (GML) coverage point is always a 0D point: on an index CRS the point is on integral coordinates, and the footprint would be half-pixel away from it, over unreachable spaces at `'0.5 GridSpacing'` distance. Truncating this footprint to the legal index space, the footprints/pixels reduce to the point itself. == Grid origin and offset vectors When assigning an index CRS as native reference system of a coverage, there are a few things that needs to be kept in mind: where to put the origin and which offset vectors (relative vectorial offsets) are needed. If you are not familiar with origin and offset vectors, please check [wiki:PetascopeUserGuide#Offsetvectorsandcoefficients this] section. `rasdaman` users are typically familiar with the '''`CRS:1`''' keyword, which is a shortcut to tell the service that you are going to use internal marray (grid) coordinates in the subset: {{{ for cov in ( ) return encode( cov[ Long:"CRS:1"(0:100), Lat:"CRS:1"(0:200) ] , "csv") }}} The ''internal'' `CRS:1` space needs not be confused with Index CRSs (although there are ways to make them coincide): an important premise is that `rasdaman`, in line with [http://www.remotesensing.org/geotiff/faq.html?What%20is%20the%20purpose%20of%20GeoTIFF%20format%20for%20satellite%20data#AxisOrder common GIS practice], puts the origin of a grid coverage in the '''upper-left''' corner of an image. This means in practice that picking the first row of an image (slice `0` on the northings axis) will return the top row, and increasing ''internal'' coordinates will yield negative steps in the geo-CRS. The internal representation of a grid is represented by an origin (usually in `[0:__:0:__:0]`) and unit integral spacing. When using index CRSs, in order to correctly visualize an image, you must take care to properly set the offset vectors. [[Image(IndexAndGrids.png, center, 90%)]] Lookig at the picture above, you can see correct and faulty ways of defining the ''external'' index representation of a grid (2D case): * '''`I quadrant (+/+)`''': origin is upperleft corner, `i`-vector is the positive `i`-versor `[1,0]` while the `j`-vector points down (`[0,-1]`) so that inverse proportionality between the second grid axis and the external `j` axis is correctly maintained. * '''`II quadrant (-/+)`''': `j`-vector is set as `[0,1]` and as a consequence the origin becomes the lower-left corner of the image: as a result we will see the image upside-down (WC*S viewpoint) * '''`III quadrant (-/-)`''': origin is correctly set in the upper-left corner, but offset vectors have norm greater than one: while this is a technically viable solution, it also means that we lose the pixel-index correspondence: one internal index step equals a jump of 2 indexes in the external representation. * '''`IV quadrant (+/-)`''': similarly, it does not make much sense to define vectors with norm less than one: moreover this solution would even prevent from slicing those point which do not lie over a legal area of the index CRS (at fractional positions). Additionally, you could observe how ''oblique'' vectors (i.e. vectors with both components != 0) are not even taken into account here (I am not declaring there are no unforeseen applications that might need such a configuration though). This example is aimed at underlining the difference between the `CRS:1` internal grid representation and the set of index CRSs. Albeit they are different concepts, they can also coincide in case ''i)'' the `i`/`j` coordinates of the origin equal the internal indexes of the grid (which is usually but not necessarily in `[0:0:__:0]`), ''ii)'' the offset vectors are the versors of the nD cartesian CS. For some hands-on `RasQL`/WC*S query, our [browser:systemtest/util/petascope.sh test datasets] are actively using index CRSs: `mr` and `rgb` are 2D un-georeferenced images, whereas `irr_cube_1` is a fictitious toy 3D cube (with irregular spacing on the third `k` dimension) which purposely synchronizes its internal and external representation. See [RasdamanTestSuites this] page for more information. == Changing axis labels A final section is dedicated to the customization of axis labels when using an Index CRS. This can be useful when migrating existing application to 9.x releases: prior versions of `rasdaman` do not support index CRSs and client applications usually require at least a change in the subsettings labels when migrating to 9.x. The management of CRSs metadata was usually done ''in house'', with default axis labels to `x`, `y`, `z`, `t`, and so on, independently of the native CRS assigned to a coverage. The outsourcing of CRS metadata handling to the [SecoreUserGuide SECORE] resolver (official [http://external.opengeospatial.org/twiki_public/CRSdefinitionResolver/WebHome OGC resolver] for CRS related resources) imposes less freedom on the choice of axis labels on one hand (you have to use the official abbreviations), while developing a more transparent and more ruled framework. While geodetic reference systems from [http://www.epsg-registry.org/ EPSG] are not customizable (let's say they are read-only CRSs), our index CRSs (and as well [PetascopeTimeHandling time] ones) are constructed by splitting each "concept" of CRS into a '''template''' and a '''parametrization''' of the template. Indeed you can see in our resolver that every `OGC:Index`''n''`D` CRS is associated with its template `OGC:.Index`''n''`D-template`, the latter being the template and the former being its parametrization. You can notice the period `.` prefix in the templates CRS code, which (like in unix file systems) denotes an hidden resource: indeed users shall not reference the templates when setting the native CRS (URI) to a coverage, but rather always use the parametrizations. A Parametrized CRS (P-CRS) is like piggy-backed on a template, and at the same time it hides it from external interfaces: it provides one or more parameters to the enduser for customizing the content of the template ''target'' CRS definition. Parameters are set by the user by means of key-value pairs in the query of a URI. When '''default''' values for all the parameters offered by a P-CRS, then querying the P-CRS URI without any query part (`?key=value[&key=value[&...]]`) is legal: the template resource is returned (that is, the template resource where parameters values have been set to their defaults defined in the P-CRS), and the user can blissfully ignore the (relative) complexities of parametrization. Our index CRSs indeed are P-CRSs with parameters to customize the labels of the axes, which by default are `i`, `j` and `k` (4+ dimensional index CRSs are yet to be defined). This was also due to the necessity to avoid label clashes when 2+ index CRSs of the same kind have to be used within the same coverage. If a P-CRS is requested with no subelement expansion (`expand=none`, but see #364), then the behind-the-scenes definition of a P-CRS can be visualized. For instance, our `OGC:Index2D` CRS is: {{{ #!xml http://rasdaman.org:8080/def/crs/OGC/0/Index2D "i" //gml:CartesianCS/gml:axis[1]/gml:CoordinateSystemAxis/gml:axisAbbrev "j" //gml:CartesianCS/gml:axis[2]/gml:CoordinateSystemAxis/gml:axisAbbrev }}} The content is sufficiently intuitive to understand that it provides two parameters -- `'first-axis-label'` and `'second-axis-label'` with defaults to `'i'` and `'j'`, respectively -- to change `gml:axisAbbrev` abbreviation of the first and second CRS axis. Thus if we want to use index CRSs but with the ''good old'' `x`/`y` labels, we need to set the following URI as native reference system: [http://rasdaman.org:8080/def/crs/OGC/0/Index2D?first-axis-label=%22x%22&second-axis-label=%22y%22 http://rasdaman.org:8080/def/crs/OGC/0/Index2D?first-axis-label="x"&second-axis-label="y"].