GDAL-MDIM-MOSAIC(1) GDAL GDAL-MDIM-MOSAIC(1)
gdal-mdim-mosaic - Build a mosaic, either virtual (VRT) or
materialized, from multidimensional datasets
Added in version 3.12.
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]
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:
-i, --input <INPUT>
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.
-o, --output <OUTPUT>
Output multidimensional dataset name. Required.
-f, --of, --format, --output-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 <KEY>=<VALUE>
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 <ARRAYS>
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.
--oo, --open-option <NAME>=<VALUE>
Dataset open option (format specific).
May be repeated.
--if, --input-format <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.
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
Even Rouault <even.rouault@spatialys.com>
1998-2026
March 20, 2026 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:
+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 <INPUT>
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.
-o, --output <OUTPUT>
Output multidimensional dataset name. Required.
-f, --of, --format, --output-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 <KEY>=<VALUE>
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 <ARRAYS>
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 <NAME>=<VALUE>
Dataset open option (format specific).
May be repeated.
--if, --input-format <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.
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-2026
March 20, 2026 GDAL-MDIM-MOSAIC(1)