[[TOC]]
= Raster library in GRASS7 =

GIS library has been split into '''G_()''' (general routines) and '''Rast_()''' (raster-related routines) part. See also [http://grass.osgeo.org/wiki/GRASS_7_ideas_collection#Raster GRASS 7 ideas collection].

Progress:
 * r38003 - selected fns [wiki:Grass7/RasterLib/ListOfFunctions moved from gislib to rasterlib]
 * Various fixes: r38005, r38006, r38007, r38008, r38010
 * Macros and structure moved to rasterlib in r38136
 * CELL (integer) raster format: make ZLIB the standard compression instead of RLE compression (trac #2349)

'''Status''': done

== Replacement raster format ==

{{{
GRASS's long-standing raster format is overdue for a major overhaul.

Below you will find some ideas and roadmaps for future work.

The idea of this page is to collect ideas and flesh out a
specification so that when the change occurs, all the
components will be in place, pitfalls expected, and
the implementation, when it comes, quick and painless. Most
importantly it can serve to keep interested parties informed
and working together instead of in parallel forks.

Any changes to the data format will necessitate a bump in
major version number (i.e. from GRASS 6 to GRASS 7) so if
possible changes should happen in the same development cycle,
and relatively minor changes should be held back in
experimental status until a major change is committed.
}}}

=== Core raster format ===

''Lead developer: Glynn Clements''

 * Storage in '''tiles''' instead of by row
  * Reasoning: Glynn said on the mailing list: "In most cases, single-level tiled storage will give you close to the same performance with a lot less complexity."
    * The G3d library already implements a tile based approach with tile caching and tile file buffer for arbitrary read and write access, have a look at [https://grass.osgeo.org/grass-stable/manuals/raster3d_layout.png G3d tile layout]
  * Function needed to check whether tiles are all null, or all the same value.
  * What tile size should be used? Could be user/program specified, or standard value of something like 64x64. If there isn't a fixed value then there should be utility program that can convert tiled rasters to different tile sizes.
    * The tile size in the G3d library is variable and can be set when a new map is created. The program r3.retile can be used to store raster3d maps with different tile size. Additionally a function is implemented to compute the optimal tile dimension for a given max size in bytes.
  * However, row-oriented storage has the advantage that you can easily skip entire rows when downsampling. Using e.g. 64x1 "tiles" would provide both optimisations, but at the expense of reduced compression, as you need a pointer (8 bytes) for each tile, and the compression has to be restarted for each tile.
 * Merge NULL file into main data array:
   * This approach is implemented in the G3d library


Notes about NULL file format
 * Current cell_misc/null file size in GRASS GIS 7: The size of the cell_misc/
=== Directory structure ===

 * Centralize map components in {{{$MAPSET/raster/$MAPNAME/*}}} instead of many {{{$MAPSET/cell/$MAPNAME}}}, etc. directories. Many library functions and modules will need to be updated. The GRASS 6 vector format has already been ported to this structure.
 * demo 2-way conversion scripts: [https://web.archive.org/web/20090301051955/http://wald.intevation.org/tracker/index.php?func=detail&aid=372&group_id=21&atid=205 Gforge patch #372]

=== Meta-data support ===

The existing raster meta-data handling is rather weak (currently stored in {{{$MAPSET/hist/$MAPNAME}}}). Total replacement will be the best option. See [wiki:Grass7/MetadataSupport metadata support].

=== Recent discussions ===

 * https://web.archive.org/web/20090316050806/http://n2.nabble.com/-GRASS5--Raster-files-suggestion%3A-new-directory-layout-td1912121.html
 * http://lists.osgeo.org/pipermail/grass-dev/2008-April/036994.html
 * http://lists.osgeo.org/pipermail/grass-dev/2008-April/037578.html
 * http://lists.osgeo.org/pipermail/grass-dev/2008-January/034772.html

Other suggestions:

 * [https://grasswiki.osgeo.org/wiki/Time_series_development Time series in GRASS] support
 * Unit Of Measurements (UOM) support
 * Scale and offset support
 * Band Interleaved by Pixel (BIP) access and Band Interleaved by Line (BIL) modes

=== Function name changes from GRASS 6 to GRASS 7 ===

See [wiki:Grass7/RasterLib/ListOfFunctions].

== Troubleshooting ==

 * To avoid the problem "ERROR: Input window changed while maps are open for read", essentially replace G_get_set_window() with Rast_get_window() - see e.g. r47601. Note that Rast_set_window() should be called before the map is opened.