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!

...

RasterDataNode API

1. A raster data node may return its own geoCoding. Either the geo-coding is
   1. the one explicitly set by RasterDataNode.setGeoCoding(gc), or
   2. derived from it's parent product's Product.sceneGeoCoding, but only if is has been explicitly set ⁽¹⁾, or
      
   3. null.
2. A raster data node must return a tile size RasterDataNode.its own affine i2m-transform (see above) getImageToModelTransform() 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 i2m-transform is
   1. retrieved from a source image, or if no such yet exists,
   2. the one explicitly set by RasterDataNode.setImageToModelTransform(i2m), or
   3. derived from its own geoCoding and the parent product's Product.modelCrs, or if this is not possible ⁽²⁾ 
   4. an IllegalStateException is thrown
3. A raster data node must return a 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 explicitly set by RasterDataNode.setTileSize(tw,th), or
   3. the value of Product.preferredTileSize

⁽¹⁾ Avoid infinite recursion, see reference raster data node

⁽²⁾ The transformation from RasterDataNode.geoCoding.imageCrs to the parent product's Product.modelCrs must be defined and must be affine.

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 scene geo-coding implies a valid scene raster size.
• A model CRS may be derived from the scene geo-coding, see implementation of ImageManager.getModelCrs(gc)
• A model CRS may be derived from a valid scene image only, if no 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.
    

...