1.. _vrt_multidimensional:
2
3================================================================================
4Multidimensional VRT
5================================================================================
6
7.. versionadded:: 3.1
8
9Multidimensional VRT is a specific variant of the :ref:`raster.vrt` format,
10dedicated to represent Multidimensional arrays, according to the
11:ref:`multidim_raster_data_model`.
12
13Here's an example of such a file:
14
15.. code-block:: xml
16
17    <VRTDataset>
18        <Group name="/">
19            <Dimension name="Y" size="4"/>
20            <Dimension name="X" size="3"/>
21
22            <Array name="temperature">
23                <DataType>Float64</DataType>
24                <DimensionRef ref="Y"/>
25                <DimensionRef ref="X"/>
26                <Source>
27                    <SourceFilename>my.nc</SourceFilename>
28                    <SourceArray>temperature</SourceArray>
29                    <SourceSlab offset="1,1" count="2,2" step="2,1"/>
30                    <DestSlab offset="2,1"/>
31                </Source>
32            </Array>
33        </Group>
34    </VRTDataset>
35
36.vrt Format
37-----------
38
39A `XML schema of the GDAL VRT format <https://raw.githubusercontent.com/OSGeo/gdal/master/gdal/data/gdalvrt.xsd>`_
40is available.
41
42Virtual files stored on disk are kept in an XML format with the following
43elements.
44
45**VRTDataset**: This is the root element for the whole GDAL dataset. It
46has no attributes, and must have a single Group child element with an attribute
47name set to "/"
48
49.. code-block:: xml
50
51    <VRTDataset>
52        <Group name="/">
53
54
55**Group**: This represents a :cpp:class:`GDALGroup`. There is at least one root
56group of name "/" immediately under the VRTDataset element. A Group must have
57a *name* attribute, and may have the following child elements, with 0:n
58multiplicity: Dimension, Attribute, Array, Group
59
60**Dimension**: This represents a :cpp:class:`GDALDimension`. It has the following
61attributes: *name* (required), *size* (required), *type* and *direction*
62
63.. code-block:: xml
64
65    <Dimension name="X" size="30" type="HORIZONTAL_X" direction="EAST"/>
66
67
68**Attribute**: This represents a :cpp:class:`GDALAttribute`. It must have a
69*name* attribute and a child *DataType* element. Attribute values are stored in
70one or several child *Value* element(s)
71
72The value of *DataType* may be: String, Byte, UInt16, Int16, UInt32, Int32,
73Float32, Float64, CInt16, CInt32, CFloat32 or CFloat64.
74
75.. code-block:: xml
76
77    <Attribute name="foo">
78        <DataType>String</DataType>
79        <Value>bar</Value>
80    </Attribute>
81
82
83**Array**: This represents a :cpp:class:`GDALMDArray`. It must have a
84*name* attribute and a child *DataType* element. It may have 0 or more
85*DimensionRef* or *Dimension* child elements to define its dimensions. And
86the following elements may be optionally specified to define its properties.
87*SRS, *Unit*, *NoDataValue*, *Offset* and *Scale*.
88To define its values, it may have one *RegularlySpacedValues* element,
89or zero, one or several elements among *ConstantValue*, *InlineValues*, *InlineValuesWithValueElement* or
90*Source*.
91
92.. code-block:: xml
93
94    <Array name="longitude">
95        <DataType>Float64</DataType>
96        <DimensionRef ref="longitude"/>
97        <RegularlySpacedValues start="-180" step="0.5"/>
98    </Array>
99
100.. code-block:: xml
101
102    <Array name="time">
103        <DataType>String</DataType>
104        <DimensionRef ref="time"/>
105        <InlineValuesWithValueElement>
106            <Value>2010-01-01</Value>
107            <Value>2011-01-01</Value>
108            <Value>2012-01-01</Value>
109        </InlineValuesWithValueElement>
110    </Array>
111
112.. code-block:: xml
113
114    <Array name="temperature">
115        <DataType>Float64</DataType>
116        <DimensionRef ref="Y"/>
117        <Dimension name="X" size="3"/>
118        <SRS dataAxisToSRSAxisMapping="2,1">EPSG:32631</SRS>
119        <Unit>Kelvin</Unit>
120        <NoDataValue>-999</NoDataValue>
121        <Offset>0</Offset>
122        <Scale>1</Scale>
123        <Source>
124            <SourceFilename>my.nc</SourceFilename>
125            <SourceArray>temperature</SourceArray>
126        </Source>
127    </Array>
128
129**Source**: This indicates that raster data should be read from a separate dataset.
130A Source must have a *SourceFilename*, and either a *SourceArray* (when the source
131is a Multidimensional dataset), or a *SourceBand* (when the source is a classic
1322D dataset) child element. It may have a *SourceTranspose* child element to apply
133a :cpp:func:`GDALMDArray::Transpose` operation and a *SourceView* to apply
134slicing/trimming operations or extraction of a component of a compound data
135type (see :cpp:func:`GDALMDArray::GetView`). It may have a *SourceSlab* element
136with attributes *offset*, *count* and *step* defining respectively the starting
137offset of the source, the number of values along each dimension and the step
138between source elements. It may have a *DestSlab* element with an *offset*
139attribute to define where the source data is placed into the target array.
140SourceSlab operates on the output of SourceView if specified, which operates
141itself on the output of SourceTranspose if specified.
142
143.. code-block:: xml
144
145        <Source>
146            <SourceFilename>my.nc</SourceFilename>
147            <SourceArray>temperature</SourceArray>
148            <SourceTranspose>1,0</SourceTranspose>
149            <SourceView>[...]</SourceView>
150            <SourceSlab offset="1,1" count="2,2" step="2,1"/>
151            <DestSlab offset="2,1"/>
152        </Source>
153