Scroll to navigation

GDAL-MDIM-MOSAIC(1) GDAL GDAL-MDIM-MOSAIC(1)

NAME

gdal-mdim-mosaic - Build a mosaic, either virtual (VRT) or materialized, from multidimensional datasets

Added in version 3.12.

SYNOPSIS

Usage: gdal mdim mosaic [OPTIONS] <INPUT>... <OUTPUT>
Build a mosaic, either virtual (VRT) or materialized, from multidimensional datasets.
Positional arguments:


  -i, --input <INPUT>                                  Input multidimensional raster datasets [1.. values] [required]


  -o, --output <OUTPUT>                                Output multidimensional raster dataset (created by algorithm) [required]
Common Options:


  -h, --help                                           Display help message and exit


  --json-usage                                         Display usage as JSON document and exit


  --config <KEY>=<VALUE>                               Configuration option [may be repeated]


  -q, --quiet                                          Quiet mode (no progress bar)
Options:


  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format


  --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated]


  --overwrite                                          Whether overwriting existing output is allowed


  --array <ARRAY>                                      Name of array(s) to mosaic. [may be repeated]
Advanced Options:


  --oo, --open-option <KEY>=<VALUE>                    Open options [may be repeated]


  --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated]


DESCRIPTION

gdal mdim mosaic builds a mosaic of multidimensional array(s), from a list of input GDAL multidimensional datasets, that can be either a virtual mosaic in the Multidimensional VRT (Virtual Dataset) format, or in a more conventional multidimensional format such as NetCDF: Network Common Data Form or Zarr.

Wildcards '*', '?' or '['] of VSIGlob() can be used for input dataset names, even on files located on network file systems such as /vsis3/, /vsigs/, /vsiaz/, etc. Alternatively if a input dataset name is prefixed by the @ character, it will be assumed to contain the list of actual dataset names (one per line) to use as input datasets.

To create a mosaic from an array, certain structural constraints apply to all contributing arrays from the input datasets:

  • All contributing arrays must have the same array name and path (e.g. "/measurements/pressure")
  • They must have the same data type and nodata value
  • They must share the same number of dimensions, in the same order, and with the same names.
  • each dimension of the array must have an associated one-dimensional numeric indexing variable.

A typical use case is when a multidimensional array is sliced into several files, and it is desired to reconstruct the full array.

The program can support mosaicing along several axes.

There might be "holes" among the source datasets along the mosaiced dimensions, and possibly overlaps (but only when regularly spacing along a mosaiced dimension). Holes are filled with the nodata value, if defined in the source arrays, or zero-initialized otherwise. In case of overlap, the order of the input list is used to determine priority. Files that are listed at the end are the ones from which the content will be fetched.

Different typical use cases that can be addressed by this program are:

  • a 3D array is sliced along a single dimension (for example a temporal one) into several files with each slice having a sample along that dimension. In that use case, the timestamps of the slices do not need to be regularly spaced.
  • a 2D array is chunked/tiled along X and Y dimensions, with a regular spacing along those X and Y dimensions, and where the coordinate values are aligned on the same grid among chunks.

By default, a target array is created for each array with two or more dimensions. This behavior can be restricted to specific arrays using the --array option.

The following options are available:

Standard options

Input multidimensional dataset names. Required.

Wildcards '*', '?' or '['] of VSIGlob() can be used for input dataset names, even on files located on network file systems such as /vsis3/, /vsigs/, /vsiaz/, etc. Alternatively if a input dataset name is prefixed by the @ character, it will be assumed to contain the list of actual dataset names (one per line) to use as input datasets.


Output multidimensional dataset name. Required.

Select the output format. This can be a format that supports multidimensional output (such as NetCDF: Network Common Data Form, Multidimensional VRT). When this option is not specified, the format is guessed when possible from the extension of the destination filename.

Many formats have one or more optional creation options that can be used to control particulars about the file created.

The creation options available vary by format driver, and some simple formats have no creation options at all. A list of options supported for a format can be listed with the --format command line option but the documentation for the format is the definitive source of information on driver creation options. See Raster drivers format specific documentation for legal creation options for each format.

Array-level creation options may be passed by prefixing them with ARRAY:. See GDALGroup::CopyFrom() for further details regarding such options.


Allow program to overwrite existing target file or dataset. Otherwise, by default, gdal errors out if the target file or dataset already exists.

Name or full path of one or several arrays to mosaic. If not specified, a target array is created for each array with two or more dimensions.

Advanced options

Dataset open option (format specific).

May be repeated.


Format/driver name to be attempted to open the input file(s). It is generally not necessary to specify it, but it can be used to skip automatic driver detection, when it fails to select the appropriate driver. This option can be repeated several times to specify several candidate drivers. Note that it does not force those drivers to open the dataset. In particular, some drivers have requirements on file extensions.

May be repeated.


EXAMPLES

Example 1: Mosaic together several all netCDF files starting with slice that are slices of a 3D array

gdal mdim mosaic slice*.nc out.vrt


AUTHOR

Even Rouault <even.rouault@spatialys.com>

COPYRIGHT

1998-2025

November 7, 2025