GDAL-MDIM-CONVERT(1) GDAL GDAL-MDIM-CONVERT(1)
gdal-mdim-convert - Convert a multidimensional dataset
Added in version 3.11.
Usage: gdal mdim convert [OPTIONS] <INPUT> <OUTPUT>
Convert a multidimensional dataset.
Positional arguments:
-i, --input <INPUT> Input raster or multidimensional raster dataset [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-SPEC> Select a single array instead of converting the whole dataset. [may be repeated]
--array-option <KEY>=<VALUE> Option passed to GDALGroup::GetMDArrayNames() to filter arrays. [may be repeated]
--group <GROUP-SPEC> Select a single group instead of converting the whole dataset. [may be repeated]
--subset <SUBSET-SPEC> Select a subset of the data. [may be repeated]
--scale-axes <SCALEAXES-SPEC> Applies a integral scale factor to one or several dimensions [may be repeated]
--strict Turn warnings into failures.
Advanced Options:
--oo, --open-option <KEY>=<VALUE> Open options [may be repeated]
--if, --input-format <INPUT-FORMAT> Input formats [may be repeated]
gdal mdim convert can be used to convert multidimensional data
between different formats.
The following options are available:
-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), or a "classic" 2D formats, if
only one single 2D array results of the other specified
conversion operations. 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 <array_spec>
Instead of converting the whole dataset, select one array, and
possibly perform operations on it. This option can be
specified several times to operate on different arrays.
<array_spec> may be just an array name, potentially using a
fully qualified syntax (/group/subgroup/array_name). Or it can
be a combination of options with the syntax:
name={src_array_name}[,dstname={dst_array_name}][,resample=yes][,transpose=[{axis1},{axis2},...][,view={view_expr}]
The following options are processed in that order:
+o resample=yes asks for the array to run through
GDALMDArray::GetResampled().
+o
[{axis1},{axis2},...] is the argument of
GDALMDArray::Transpose().
For example, transpose=[1,0] switches the axis order
of a 2D array. See Example 6.
+o {view_expr} is the value of the viewExpr argument of
GDALMDArray::GetView(). See Example 5.
When specifying a view_expr that performs a slicing or
subsetting on a dimension, the equivalent operation will be
applied to the corresponding indexing variable.
--array-option <NAME>=<VALUE>
Option passed to GDALGroup::GetMDArrayNames() to filter
reported arrays. Such option is format specific. Consult
driver documentation. This option may be used several times.
--group <group_spec>
Instead of converting the whole dataset, select one group, and
possibly perform operations on it. This option can be
specified several times to operate on different groups. If
only one group is specified, its content will be copied
directly to the target root group. If several ones are
specified, they are copied under the target root group
<group_spec> may be just a group name, potentially using a
fully qualified syntax (/group/subgroup/subsubgroup_name). Or
it can be a combination of options with the syntax:
name={src_group_name}[,dstname={dst_group_name}][,recursive=no]
--subset <subset_spec>
Performs a subsetting (trimming or slicing) operation along a
dimension, provided that it is indexed by a 1D variable of
numeric or string data type, and whose values are
monotonically sorted. <subset_spec> follows exactly the OGC
WCS 2.0 KVP encoding for subsetting.
That is dim_name(min_val,max_val) or dim_name(sliced_val) The
first syntax will subset the dimension dim_name to values in
the [min_val,max_val] range. The second syntax will slice the
dimension dim_name to value sliced_val (and this dimension
will be removed from the arrays that reference to it)
Beware that dimension name is case sensitive.
Several subsetting operations along different dimensions can
be specified by repeating the option.
Using --subset is incompatible with specifying a view option
in --array.
See Example 2 or Example 3.
--scale-axes <scaleaxes_spec>
Applies a integral scale factor to one or several dimensions,
that is extract 1 value every N values (without resampling).
<scaleaxes_spec> follows exactly the syntax of the KVP
encoding of the SCALEAXES parameter of OGC WCS 2.0 Scaling
Extension, but limited to integer scale factors.
That is <dim1_name>(<scale_factor>).
Several scaling operations along different dimensions can be
specified by repeating the option.
Using --scale-axes is incompatible with specifying a view
option in --array.
See Example 4.
--strict
By default, some failures during the translation are
tolerated, such as not being able to write group attributes.
When setting this option, such failures will cause the process
to fail.
--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: Convert a netCDF file to a multidimensional VRT file
gdal mdim convert in.nc out.vrt
Example 2: Extract a 2D slice of a time,Y,X array
gdal mdim convert in.nc out.tif --subset "time(\"2010-01-01\")" --array temperature
Example 3: Extract a a 3D chunk from a time-indexed GRIB file into a
multiband GeoTIFF.
gdal mdim convert /vsicurl/https://tgftp.nws.noaa.gov/SL.us008001/ST.opnl/DF.gr2/DC.ndfd/AR.conus/VP.001-003/ds.qpf.bin tst.tif --subset "TIME(1763164800,1763251200)" --array QPF_0-SFC --co COMPRESS=DEFLATE
Example 4: Subsample along x and y axis
gdal mdim convert in.nc out.nc --scale-axes "x(2),y(2)"
Example 5: Reorder the values of an array
Reorder the values of the time,Y,X array along the Y axis from
top-to-bottom to bottom-to-top (or the reverse)
gdal mdim convert in.nc out.nc --array "name=temperature,view=[:,::-1,:]"
Example 6: Transpose an array that has X,Y,time dimension order to
time,Y,X
gdal mdim convert in.nc out.nc --array "name=temperature,transpose=[2,1,0]"
Even Rouault <even.rouault@spatialys.com>
1998-2026
March 20, 2026 GDAL-MDIM-CONVERT(1)
NAME
gdal-mdim-convert - Convert a multidimensional dataset
Added in version 3.11.
SYNOPSIS
Usage: gdal mdim convert [OPTIONS] <INPUT> <OUTPUT>
Convert a multidimensional dataset.
Positional arguments:
-i, --input <INPUT> Input raster or multidimensional raster dataset [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-SPEC> Select a single array instead of converting the whole dataset. [may be repeated]
--array-option <KEY>=<VALUE> Option passed to GDALGroup::GetMDArrayNames() to filter arrays. [may be repeated]
--group <GROUP-SPEC> Select a single group instead of converting the whole dataset. [may be repeated]
--subset <SUBSET-SPEC> Select a subset of the data. [may be repeated]
--scale-axes <SCALEAXES-SPEC> Applies a integral scale factor to one or several dimensions [may be repeated]
--strict Turn warnings into failures.
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 convert can be used to convert multidimensional data
between different formats.
The following options are available:
Standard options
-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), or a "classic" 2D formats, if
only one single 2D array results of the other specified
conversion operations. 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 <array_spec>
Instead of converting the whole dataset, select one array, and
possibly perform operations on it. This option can be
specified several times to operate on different arrays.
<array_spec> may be just an array name, potentially using a
fully qualified syntax (/group/subgroup/array_name). Or it can
be a combination of options with the syntax:
name={src_array_name}[,dstname={dst_array_name}][,resample=yes][,transpose=[{axis1},{axis2},...][,view={view_expr}]
The following options are processed in that order:
+o resample=yes asks for the array to run through
GDALMDArray::GetResampled().
+o
[{axis1},{axis2},...] is the argument of
GDALMDArray::Transpose().
For example, transpose=[1,0] switches the axis order
of a 2D array. See Example 6.
+o {view_expr} is the value of the viewExpr argument of
GDALMDArray::GetView(). See Example 5.
When specifying a view_expr that performs a slicing or
subsetting on a dimension, the equivalent operation will be
applied to the corresponding indexing variable.
--array-option <NAME>=<VALUE>
Option passed to GDALGroup::GetMDArrayNames() to filter
reported arrays. Such option is format specific. Consult
driver documentation. This option may be used several times.
--group <group_spec>
Instead of converting the whole dataset, select one group, and
possibly perform operations on it. This option can be
specified several times to operate on different groups. If
only one group is specified, its content will be copied
directly to the target root group. If several ones are
specified, they are copied under the target root group
<group_spec> may be just a group name, potentially using a
fully qualified syntax (/group/subgroup/subsubgroup_name). Or
it can be a combination of options with the syntax:
name={src_group_name}[,dstname={dst_group_name}][,recursive=no]
--subset <subset_spec>
Performs a subsetting (trimming or slicing) operation along a
dimension, provided that it is indexed by a 1D variable of
numeric or string data type, and whose values are
monotonically sorted. <subset_spec> follows exactly the OGC
WCS 2.0 KVP encoding for subsetting.
That is dim_name(min_val,max_val) or dim_name(sliced_val) The
first syntax will subset the dimension dim_name to values in
the [min_val,max_val] range. The second syntax will slice the
dimension dim_name to value sliced_val (and this dimension
will be removed from the arrays that reference to it)
Beware that dimension name is case sensitive.
Several subsetting operations along different dimensions can
be specified by repeating the option.
Using --subset is incompatible with specifying a view option
in --array.
See Example 2 or Example 3.
--scale-axes <scaleaxes_spec>
Applies a integral scale factor to one or several dimensions,
that is extract 1 value every N values (without resampling).
<scaleaxes_spec> follows exactly the syntax of the KVP
encoding of the SCALEAXES parameter of OGC WCS 2.0 Scaling
Extension, but limited to integer scale factors.
That is <dim1_name>(<scale_factor>).
Several scaling operations along different dimensions can be
specified by repeating the option.
Using --scale-axes is incompatible with specifying a view
option in --array.
See Example 4.
--strict
By default, some failures during the translation are
tolerated, such as not being able to write group attributes.
When setting this option, such failures will cause the process
to fail.
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: Convert a netCDF file to a multidimensional VRT file
gdal mdim convert in.nc out.vrt
Example 2: Extract a 2D slice of a time,Y,X array
gdal mdim convert in.nc out.tif --subset "time(\"2010-01-01\")" --array temperature
Example 3: Extract a a 3D chunk from a time-indexed GRIB file into a
multiband GeoTIFF.
gdal mdim convert /vsicurl/https://tgftp.nws.noaa.gov/SL.us008001/ST.opnl/DF.gr2/DC.ndfd/AR.conus/VP.001-003/ds.qpf.bin tst.tif --subset "TIME(1763164800,1763251200)" --array QPF_0-SFC --co COMPRESS=DEFLATE
Example 4: Subsample along x and y axis
gdal mdim convert in.nc out.nc --scale-axes "x(2),y(2)"
Example 5: Reorder the values of an array
Reorder the values of the time,Y,X array along the Y axis from
top-to-bottom to bottom-to-top (or the reverse)
gdal mdim convert in.nc out.nc --array "name=temperature,view=[:,::-1,:]"
Example 6: Transpose an array that has X,Y,time dimension order to
time,Y,X
gdal mdim convert in.nc out.nc --array "name=temperature,transpose=[2,1,0]"
AUTHOR
Even Rouault <even.rouault@spatialys.com>
COPYRIGHT
1998-2026
March 20, 2026 GDAL-MDIM-CONVERT(1)