Current Multi-Size API (as of 02.10.2015)

...

• getImageToModelTransform(GeoCoding): Calls GeoCoding.getImageToMapTransform to check if it is affine, if so, returns it, otherwise returns identity ⁽¹⁾.  22 usages

• getModelCrs(GeoCoding): Calls GeoCoding.getImageToMapTransform to check if it is affine, if so, returns GeoCoding.mapCrs, otherwise GeoCoding.imageCrs. 22 usages


• getMultiLevelModel(RasterDataNode): Used to derive a multi-level image model from a raster data node's source image, otherwise calls createMultiLevelModel.⁽²⁾ 26 usages
• createMultiLevelModel(ProductNode): Used to create a default multi-level image model. Calls getImageToModelTransform, uses Product.numResolutionsMax.⁽²⁾  9 usages
• getPreferredTileSize(Product) Gets the preferred tile size of a product or computes a new one. 16 usages
  
  

⁽¹⁾ Returning the identity transformation by default is probably wrong in many cases, because then images of any size would return the same transformation into a common model CRS!

...

The following is a proposal for a reinterpretation of Product properties and methods and a description of new ones: 

1. A data Product contains
   1. Vector data
   2. Raster data,
      1. with same or different image raster sizes
      2. with same or different or without geo-coding assigned
2. A product has a model coordinate reference system (model CRS) which is common to all the product components
   1. Vector data geometries are always given in model coordinates⁽¹⁾
   2. Raster data images provide an AffineTransformation from image pixel coordinates to model coordinates
3. A product must always return valid model CRS via Product.getModelCrs(). Either the model CRS
   1. is passed to a constructor, or
   2. is explicitly set using Product.setModelCrs(crs), or
   3. is derived from a reference raster data node⁽²⁾⁽³⁾, or if no such exists
   4. an IllegalStateException is thrown
4. A product must return a non-zero reference scene raster size via Product.getReferenceRasterSizegetSceneRasterSize(). Note that Pins and GCPs have a pixelPos attribute that refers to the reference raster's grid. Also, TiePointGrids interpolate from their local raster data grid into the reference raster's grid. Either the reference scene raster size
   1. is passed to a constructor, or
   2. is explicitly set using Product.setReferenceSceneRasterSize(size), or
   3. is derived from a reference raster data node, or if no such exists
   4. an IllegalStateException is thrown
5.  A product must return an affine transformation from the reference raster grid to the model CRS (i2m-transform) via Product.getReferenceImageToModelTransformgetSceneImageToModelTransform(). Either the i2m-transform
   1. is passed to a constructor, or
   2. is explicitly set using Product.setReferenceSceneImageToModelTransform(i2mT), or
   3. is derived from a reference raster data node⁽⁴⁾, or if no such exists
   4. an IllegalStateException is thrown
6. A product may return a reference scene geo-coding via Product.getReferenceSceneGeoCoding() providing the transformation from the reference scene raster coordinates to geographical coordinates. Therefore, a reference geo-coding implies a valid reference scene raster size. Either the reference scene geo-coding
   1. is passed to a constructor, or
   2. is explicitly set using Product.setReferenceSceneGeoCoding(geoCoding), or
   3. is derived from a reference raster data node, or if no such exists
   4. null is returned
7. A product must return a preferred tile size for all raster data nodes⁽⁵⁾ via Product.getPreferredTileSize(). Either the preferred tile size 
   1. is explicitely set by Product.setPreferredTileSize(tw,th), or
   2. a default tile size is computed from the reference raster size, or if no such exists
   3. (512, 512) is returned.
   A product must return a preferred tile size for a specific image size via Product.getPreferredTileSize

⁽

...

1. is explicitely set by Product.setPreferredTileSize(iw, ih, tw,th), or
2. a default tile size is computed for (iw,ih).

⁽¹⁾ Vector data are represented by SimpleFeature which can provide a CRS for their default geometry. Howver, in SNAP we use a common coordinate system for all vector data therefore a single model CRS is required per product. Pins and GCPs also have a pixelPos attribute. Its value must be given in reference scene raster coordinates.

⁽²⁾ Obtaining the reference raster data node could be done as follows:

...

⁽⁵⁾ A client may wish to force all images of all raster data nodes to have the same tile size regardless of their actual image size. This may or may not be useful for a particular product type instance. Also, it may make sense to force the tile cache to contain single size tiles for maximum memory reuse.

RasterDataNode API

1. A raster data node must return a tile size RasterDataNode.tileSize that is used by it's source image or that will be used for any source image as long as it hasn't been created so far. Either the tile size is
   1. retrieved from a source image, or if no such yet exists,
   2. the one explicitely set by RasterDataNode.setTileSize(tw,th), or
   3. the value of Product.preferredTileSize

Facts and Consequences

• Every product instance must have a model CRS. As a consequence, in order to save products in DIMAP- or -NetCDF format, they must be made persistable.
• A reference scene geo-coding implies a valid reference scene raster size.
• A model CRS may be derived from the reference the scene geo-coding, see implementation of ImageManager.getModelCrs(gc)
• A model CRS may be derived from a valid reference scene image only, if no reference scene geo-coding is specified.
• All i2m-transforms are affine (linear) transformations.
• The Product.addBand(name, ...) and addMask(name, ...) methods must throw an IllegalStateException if no valid reference raster size is defined.
• Note that it is still confusing to API users that we
  
  • use the terms image, raster, pixel, sample in an inconsistent manner in property/method names in RasterDataNode and also Tile (GPF); 
  • have map, geo and image CRS in the GeoCoding API, but a model CRS in the Product API (four CRS!). Luckily, API users usually don't deal with that too much.
    

...

1. Concerning points 1 to 6 and considering the actual use of these properties: is default a better name than reference, or even stay with scene?
   Answer (NF): scene is not bad because it refers to the satellite footprint or spatial coverage, reference iis more neutral (because we don't always have footprints or spatial coverage), default is only useful concerning the Product.addBand(name,...) and addMask(name, ..) methods. May may stay with scene, to minimze refactorings and maximize compatibility. Problematic are other uses of scene such as in ProductSceneView. On the other hand, the Layers used in such a view all share the model CRS. We could argument, that whenever we say scene, we refer to model coordinates.
   Decision: We stay with scene in API names which may be derived from a reference raster data node.
   
2. RasterDataNode currently has a rasterSize property and also a sceneRasterSize property which are the same in most cases, but usually different for a TiePointGrid. Once sceneRasterSize is reinterpreted as referenceRasterSizereinterpreted in this new sense, then rasterSize should refer to the actual size of the raster data in use. But since a TiePointGrid automatically expand its data to the referenceRasterSize sceneRasterSize, its actual raster size is the reference raster size. How can we avoid this ambiguity?
   Answer (NF): Hide the actual tie point grid size as an implementation detail in TiePointGrid.  
   1. Carefully visit and analyse all current RasterDataNode.rasterWith/Height/Size as well as RasterDataNode.get/setRasterData and RasterDataNode.getSceneRasterData usages.
      
   2. Then let RasterDataNode.rasterWith/Height/Size return the actual raster size with respect to a multi-size product, change context code accordingly (should only affect TiePointGrid usages).
      
   3. Replace current RasterDataNode.sceneRasterWidth/Height/Size usages by RasterDataNode.rasterWith/Height/Size.
      
   4. Completely remove RasterDataNode.sceneRasterWidth/Height/Size properties.  
   5. Replace current RasterDataNode.getSceneRasterData usages by RasterDataNode.getRasterData.
   6. Completely remove RasterDataNode.sceneRasterData method.   
      
3. Why do we need a pixelPos attribute for Pins and GCPs? The product's model CRS is either the GeoCoding.mapCrs or some image CRS referring to the reference raster size. Therefore there is always a linear transformation from the model CRS to the image CRS anyway.
   Answer (NF): Check actual usage of pixelPos. If it is not too much work, remove the attribute completly, use the geometry field instead as it seems the most generic and non-redundant information.

...

• revisit existing Product constructors and change according to requirements 1 to 6. 
• add Product.get/setModelCrs methods. Implement getModelCrs method according to point 3 above
• rename reimplement Product.getSceneRasterSize into getReferenceRasterSize. Implement method  according to point 4 above (we may stay with sceneRasterSize, see above Q&A 1)
  

...

...