GDAL-MDIM-CONVERT(1)

📦

version 3.13.3 · 7 versions

3.13.3 · alpine 3.24, arch rolling, ubuntu stonking (latest)
3.11.3 · opensuse-leap 16.0
3.11.5 · fedora 43
3.11.4 · fedora 43
3.12.4 · fedora 44
3.12.3 · fedora 44
3.12.2 · ubuntu resolute

, in alpine 3.24, arch rolling, ubuntu stonking

💖 gdal-mdim-convert 💖

Hiii bestie!! 🫶 Welcome to GDAL-MDIM-CONVERT(1), one of the many gorgeous pages in the GDAL manual. Yes, the header technically says GDAL-MDIM-CONVERT(1) ... GDAL ... GDAL-MDIM-CONVERT(1), but you don't need that, you need ME walking you through it. Sit down, grab a strawberry 🍓, and let's convert some multidimensional datasets together. No cap.

🌸 NAME 🌸

gdal-mdim-convert — convert a multidimensional dataset, bestie. That's the whole job. ✨

Added in version 3.11. So if you're on an older GDAL, this one isn't gonna show up for you. Upgrade era only, sorry. 💅

✨ 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 or warning message) [not available in pipelines]

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 dataset 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 is literally here to convert multidimensional data between different formats. That's it, that's the whole vibe. 👑

The following options are available:

🌈 Standard options 🌈

-f, --of, --format, --output-format _<OUTPUT-FORMAT>_ — Pick the output format, bestie. This can be a format that supports multidimensional output (like NetCDF: Network Common Data Form, or Multidimensional VRT), OR a "classic" 2D format — but only if the other conversion operations you specified leave you with exactly one single 2D array as the result. If you don't pass this option at all, the format gets guessed when possible from the extension of the destination filename. Psychic behavior, we love her. 🔮
--co, --creation-option _<KEY>=<VALUE>_ — So many formats have one or more optional creation options, and those bad boys control the particulars of the file being created. The creation options available vary by format driver, and ngl some simple formats have no creation options at all — nothing to offer, and that's okay. You can list the options a format supports with the --format command line option, but heads up: the documentation for the format itself is the definitive source of info on driver creation options. See Raster drivers format specific documentation for the legal creation options for each format. And plot twist — array-level creation options can be passed by prefixing them with ARRAY:. See GDALGroup::CopyFrom() for further details regarding such options. 💅
--overwrite — Lets the program overwrite an existing target file or dataset. Otherwise, by default, gdal errors out if the target file or dataset already exists. So without this flag, she says no. 🚫
--array _<array_spec>_ — Instead of converting the whole entire dataset, select one array, and possibly do some operations on it. You can specify this option several times to operate on different arrays. Go off, multitasker.

_<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:

resample=yes asks for the array to run through GDALMDArray::GetResampled().
[{axis1},{axis2},...] is the argument of GDALMDArray::Transpose(). For example, transpose=[1,0] switches the axis order of a 2D array. See Example 6.
{view_expr} is the value of the viewExpr argument of GDALMDArray::GetView(). See Example 5.

When you specify a view_expr that performs a slicing or subsetting on a dimension, the equivalent operation will be applied to the corresponding indexing variable. The universe keeps things consistent like that. 🧚

--array-option _<NAME>=<VALUE>_ — An option passed to GDALGroup::GetMDArrayNames() to filter reported arrays. Such an option is format specific, so consult the driver documentation, bestie. 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. You can specify this option several times to operate on different groups. Here's the tea: 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. (No period at the end of that sentence in the original, and honestly? Respect the chaos. 💀)

_<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. Type carefully, queen. 🔥

Several subsetting operations along different dimensions can be specified by repeating the option.

🚨 Using --subset is incompatible with specifying a view option in --array. Pick a lane, bestie.

See Example 2 or Example 3.

--scale-axes _<scaleaxes_spec>_ — Applies an integral scale factor to one or several dimensions, that is: extract 1 value every N values (without resampling). She's just skipping through, not re-mixing. 🎀

_<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. Again: pick a lane!!

See Example 4.

--strict — By default, some failures during the translation are tolerated, such as not being able to write group attributes, and honestly she just lets it slide. When you set this option, such failures will cause the process to fail. No more being chill. Periodt. 💅

⭐ 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 when opening 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 — and in particular, some drivers have requirements on file extensions. Manifestation only goes so far, iykyk. ✨

May be repeated.

👑 RETURN STATUS CODE 👑

The program returns status code 0 in case of success, and non-zero in case of error. But plot twist bestie: non-blocking errors emitted as warnings are considered as a successful execution. So a little warning here and there is not a failure, it's just her being honest. 💖

💫 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.

(Yes, the title says "a a". We are not fixing it. It's iconic. 👑)

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). Flipping the whole fit, honestly. 🙃

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> — the main character who wrote all this. Respect. 🌟

💅 COPYRIGHT 💅

1998-2026

And that's the whole page, bestie!! 🎀 Source: the GDAL manual, page GDAL-MDIM-CONVERT(1), dated Aug 18, 2026. Go convert something gorgeous. Mwah. 💖✨🦋

📦 where this page comes from

alpine 3.24: gdal-doc 3.13.3-r0 · MIT
arch rolling: gdal 3.13.3-6 · MIT
ubuntu stonking: gdal-bin 3.13.3+dfsg-1ubuntu4 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms