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]
Build a mosaic, either virtual (VRT) or materialized, from multidimensional datasets.
Positional arguments:
-i, --input 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 = Configuration option [may be repeated]
-q, --quiet Quiet mode (no progress bar or warning message) [not available in pipelines]
Options:
-f, --of, --format, --output-format Output format
--co, --creation-option = Creation option [may be repeated]
--overwrite Whether overwriting existing output dataset is allowed
--array Name of array(s) to mosaic. [may be repeated]
Advanced Options:
--oo, --open-option = Open options [may be repeated]
--if, --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:
o All contributing arrays must have the same array name and path (e.g.
"/measurements/pressure")
o They must have the same data type and nodata value
o They must share the same number of dimensions, in the same order, and
with the same names.
o 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:
o 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.
o 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
-i, --input
Output multidimensional dataset name. Required.
-f, --of, --format, --output-format
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.
--co, --creation-option =
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.
--overwrite
Allow program to overwrite existing target file or dataset.
Otherwise, by default, gdal errors out if the target file or
dataset already exists.
--array
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
--oo, --open-option =
Dataset open option (format specific).
May be repeated.
--if, --input-format
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.
RETURN STATUS CODE
The program returns status code 0 in case of success, and non-zero in
case of error (non-blocking errors emitted as warnings are considered
as a successful execution).
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
COPYRIGHT
1998-2026
August 18, 2026 GDAL-MDIM-MOSAIC(1)