/
NXregion.nxdl.xml
193 lines (180 loc) · 7.56 KB
/
NXregion.nxdl.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl" ?>
<!--
# NeXus - Neutron and X-ray Common Data Format
#
# Copyright (C) 2013-2024 NeXus International Advisory Committee (NIAC)
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 3 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# For further information, see http://www.nexusformat.org
-->
<definition
category="base"
xmlns="http://definition.nexusformat.org/nxdl/3.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
name="NXregion"
type="group" extends="NXobject">
<symbols>
<doc>
These symbols will denote how the shape of the parent group's data field,
.. math:: (D_0, ..., D_{\mathbf{O}-1}, d_0, ..., d_{\mathbf{R}-1})
could be split into a left set of **O** outer dimensions, :math:`\boldsymbol{D}`,
and a right set of **R** region dimensions, :math:`\boldsymbol{d}`,
where the data field has rank **O** + **R**. Note **O** :math:`>= 0`.
</doc>
<symbol name="O"><doc>Outer rank</doc></symbol>
<symbol name="R"><doc>Region rank</doc></symbol>
</symbols>
<doc>
Geometry and logical description of a region of data in a parent group. When used, it could be a child group to, say, :ref:`NXdetector`.
This can be used to describe a subset of data used to create downsampled data or to derive
some data from that subset.
Note, the fields for the rectangular region specifiers follow HDF5’s dataspace hyperslab parameters
(see https://portal.hdfgroup.org/display/HDF5/H5S_SELECT_HYPERSLAB). Note when **block** :math:`= 1`,
then **stride** :math:`\equiv` **step** in Python slicing.
For example, a ROI sum of an area starting at index of [20,50] and shape [220,120] in image data::
detector:NXdetector/
data[60,256,512]
region:NXregion/
@region_type = "rectangular"
parent = "data"
start = [20,50]
count = [220,120]
statistics:NXdata/
@signal = "sum"
sum[60]
the ``sum`` dataset contains the summed areas in each frame.
Another example, a hyperspectral image downsampled 16-fold in energy::
detector:NXdetector/
data[128,128,4096]
region:NXregion/
@region_type = "rectangular"
parent = "data"
start = [2]
count = [20]
stride = [32]
block = [16]
downsampled:NXdata/
@signal = "maximum"
@auxiliary_signals = "copy"
maximum[128,128,20]
copy[128,128,320]
the ``copy`` dataset selects 20 16-channel blocks that start 32 channels apart,
the ``maximum`` dataset will show maximum values in each 16-channel block
in every spectra.
</doc>
<attribute name="region_type" optional="false">
<doc>
This is ``rectangular`` to describe the region as a hyper-rectangle in
the index space of its parent group's data field.
</doc>
<enumeration>
<item value="rectangular" />
</enumeration>
</attribute>
<field name="parent">
<doc>
The name of data field in the parent group or the path of a data field relative
to the parent group (so it could be a field in a subgroup of the parent group)
</doc>
</field>
<field name="parent_mask">
<doc>
The name of an optional mask field in the parent group with rank :math:`\boldsymbol{R}` and
dimensions :math:`\boldsymbol{d}`. For example, this could be ``pixel_mask`` of an
:ref:`NXdetector`.
</doc>
</field>
<field name="start" type="NX_NUMBER" recommended="true">
<doc>
The starting position for region in detector data field array.
This is recommended as it also defines the region rank.
If omitted then defined as an array of zeros.
</doc>
<dimensions rank="1">
<dim index="1" value="R"/>
</dimensions>
</field>
<field name="count" type="NX_INT" recommended="true">
<doc>
The number of blocks or items in the hyperslab selection.
If omitted then defined as an array of dimensions that take into account
the other hyperslab selection fields to span the parent data field's shape.
</doc>
<dimensions rank="1">
<dim index="1" value="R"/>
</dimensions>
</field>
<field name="stride" type="NX_INT">
<doc>
An optional field to define striding used to downsample data.
If omitted then defined as an array of ones.
</doc>
<dimensions rank="1">
<dim index="1" value="R"/>
</dimensions>
</field>
<field name="block" type="NX_INT">
<doc>
An optional field to define the block size used to copy or downsample data. In the
:math:`i`-th dimension, if :math:`\mathbf{block}[i] < \mathbf{stride}[i]`
then the downsampling blocks have gaps between them; when ``block`` matches ``stride``
then the blocks are contiguous; otherwise the blocks overlap.
If omitted then defined as an array of ones.
</doc>
<dimensions rank="1">
<dim index="1" value="R"/>
</dimensions>
</field>
<field name="scale" type="NX_NUMBER">
<doc>
An optional field to define a divisor for scaling of reduced data. For example, in a
downsampled sum, it can reduce the maximum values to fit in the domain of the result
data type. In an image that is downsampled by summing 2x2 blocks, using
:math:`\mathrm{scale}=4` allows the result to fit in the same integer type dataset as
the parent dataset.
If omitted then no scaling occurs.
</doc>
<dimensions rank="1">
<dim index="1" value="R"/>
</dimensions>
</field>
<group name="downsampled" type="NXdata">
<doc>
An optional group containing data copied/downsampled from parent group’s data. Its dataset name
must reflect how the downsampling is done over each block. So it could be a reduction operation
such as sum, minimum, maximum, mean, mode, median, etc. If downsampling is merely copying each
block then use "copy" as the name. Where more than one downsample dataset is written
(specified with ``@signal``) then add ``@auxiliary_signals`` listing the others. In the copy case,
the field should have a shape of :math:`(D_0, ..., D_{\mathbf{O}-1}, \mathbf{block}[0] * \mathbf{count}[0], ..., \mathbf{block}[\mathbf{R}-1] * \mathbf{count}[\mathbf{R}-1])`,
otherwise the expected shape is :math:`(D_0, ..., D_{\mathbf{O}-1}, \mathbf{count}[0], ..., \mathbf{count}[\mathbf{R}-1])`.
The following figure shows how blocks are used in downsampling:
.. figure:: region/NXregion-example.png
:width: 60%
A selection with :math:`\mathbf{start}=2, \mathbf{count}=4, \mathbf{stride}=3, \mathbf{block}=2` from
a dataset with shape [13] will result in the ``reduce`` dataset of shape [4] and a ``copy`` dataset of shape [8].
</doc>
</group>
<group name="statistics" type="NXdata">
<doc>
An optional group containing any statistics derived from the region in parent group’s data
such as sum, minimum, maximum, mean, mode, median, rms, variance, etc. Where more than one
statistical dataset is written (specified with ``@signal``) then add ``@auxiliary_signals``
listing the others. All data fields should have shapes of :math:`\boldsymbol{D}`.
</doc>
</group>
</definition>