cutline process flow

Cutline - Process flow

[--> 'List of Sql-Commands'] (Home#commands)

[<-- 'Index Page for RasterLite2 - Commands'] (RasterLite2-Index#commands)

[<-- 'Cutline / RasterDefaults Index'] (Cutline-Index#cutline)

---

Goal:

• to implement, when EXPORTING, a similar functionality as GDAL
  • cutline
  • crop_to_cutline

---

Problem 01:

• checking for valid input parameters
  • there a about 27 functions (plus rl2tools) that export images
    • not all of which are useful / practical for Cutline support
      • but since they (later) use the common functions
        • needed to be taken into consideration
  • almost all (if not all), checked the input parameters

Thus the need arised to centralize this common checking

• r2dbms.c rl2_resolve_image_sanity was created for this purpose
  • including the extra logic used in rl2tools

At present, all of these functions will fail

• if no or an invalid image size is given
  • although when a valid resolution and extent is given
    • this is no problem

With crop_to_cutline

• it is unrealistic to assume
  • that a User will set a valid size based on the geometry extent

Also sanity checks for a valid cutline geometry is needed

• and to deal with that in 27+ functions
  • would become a maintenance nightmare

So Stage 01 of this task

• was getting everything to work with rl2_resolve_image_sanity

---

Problem 02:

• what conditions must be fulfilled

  • to insure that a valid cutline geometry is being used

• r2dbms.c create_cutline_geometry was created for this purpose

  • which is only called from rl2_resolve_image_sanity
    • after all other checks have been completed
      • a valid extent is needed for correct results

The geometry must be

• either a POLYGON or a closed LINESTRING
  • thus also not NULL

After these first conditions have been fulfilled

• the geometry will be
  • Transformed to the srid of the raster_coverage, when needed
  • conversion to a XY geometry was done in the first step

If Croping is not being used

• the geometry will be reduced to the Area being extracted (extent)

If Croping is being used

• the Area being extracted will extended or reduced to the extent of the geometry
  • which may cause memory problems with high resolution images
    • and large geometry extents
      • for which no checking is done

If considered valid

• the adapted geometry
  • and a possibly adapted Area to be extracted

will be set inside rl2_resolve_image_sanity

• with any needed adjustments to the image size being done

Note:

• rl2_resolve_image_sanity
  • will receive from the caller a indirect pointer
    • for the final cutline geometry and an int for the size
      • these are set in create_cutline_geometry
      • and later must be freed by the caller
    • at this point the Crop has been completed
    • either the indirect pointer is NULL or not (and the size > 0)

---

Stage 02

• once rl2_resolve_image_sanity has completed
  • the final cutline geometry (and not the input cutline geometry)
    • *geom_cutline_blob and *geom_cutline_blob_sz
    • must be past on to the next functions (is NULL or not)
      • when NULL, every will run exactly as before

Until Stage 03 they are otherwise not used.

---

Stage 03

• in r2dbms.c
  • rl2_get_raw_raster_data_common
  • get_triple_band_raw_raster_data_common
  • get_mono_band_raw_raster_data_common

Sql to retrieve the needed tiles are prepared

• here the Sql will be adapted if geom_cutline_blob != NULL
  • only tiles will be retrieved that are
    • partially [ST_Contains returns 0]
    • completely [ST_Contains returns 1]

in the cutline geometry.

Goal:

• later ST_Contains calls should only be done on tile
  • that are partially inside cutline geometry

---

Stage 04

• r2dbms.c rl2_load_dbms_tiles_common

Here the prepared Sql will be executed and

• the AuxDecoder array filled

For tiles that are partially inside cutline geometry

• geom_contains == 1
  • a ST_Intersection is done from the original cutline geometry
    • and stored in the ** decoder->geom_cutline_blob*
      • together with the
        • size of the geometry
        • the database driver

The database driver is needed later for the ST_Contains command on the pixels

Goal:

• the final ST_Contains
  • should use the smallest possible geometry to check

---

Stage 05

• rl2rastersym.c rl2_copy_raw_pixels
  • calls do_copy_raw_pixels
    • which will cal the needed copy_???_raw_pixels function
      • passing on the
        • geom_cutline_blob
        • geom_cutline_blob_sz
        • the database handler

---

Stage 06

• rl2rastersym.c copy_???_raw_pixels

After the raw pixel has been extracted

• and after all other task have been completed
  • and the raw pixel is not transparent
    • and a valid cutline is supplied
      • rl2rastersym.c cutline_contains_point is called

The pixel will be set to transparent, when 0 is returned.

---

Notes:

• cutline_contains_point
  • is the slowest portion of this process
    • thus the need to get the slimiest possible geometry to check
  • this functionality should never be used by functions such as
    • RL2_GetMapImageFromRaster

---

[<-- 'Cutline / RasterDefaults Index'] (Cutline-Index#cutline)

---

2015-11-12: Mark Johnson, Berlin Germany

---