You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
| `"chunk_shapes"` | array of [Chunk edge lengths](#chunk-edge-lengths) | yes | The length of `"chunk_shapes"` MUST match the number of dimensions of the array.
60
+
|`kind`| Literal `"inline"`| yes | see [kinds of encodings](#kinds-of-encodings)|
61
+
| `chunk_shapes` | array of [Chunk edge lengths](#chunk-edge-lengths) | yes | The length of `chunk_shapes` MUST equal the number of dimensions of the array.
62
+
63
+
#### Kinds of encodings
64
+
65
+
This specification defines a single permitted value for the `kind` field, namely the string
66
+
`"inline"`. Additions to this specification could define new permitted values for the `kind` field
67
+
which could define new semantics for the `chunk_shapes` field
16
68
17
69
#### Chunk edge lengths
18
70
19
-
The edge lengths of the chunks along an array axis `A` are represented by an array that can contain two types of elements:
20
-
- an integer that explicitly denotes an edge length.
21
-
- an array that denotes a [run-length encoded](#run-length-encoding) sequence of integers, each of which denotes an edge length.
71
+
The edge lengths of the chunks for an array axis with length `L` can be declared in two ways.
22
72
23
-
The sum of the edge lengths MUST match the length of the array along the axis `A`.
73
+
- as an integer
74
+
75
+
A single integer defines the step size of a regular 1-dimensional grid.
76
+
77
+
To convert a single integer `m` into a sequence of explicit chunk edge lengths for an array axis
78
+
with length `L`, repeat the integer `m` until it defines a sequence with a sum greater than or equal to `L`.
79
+
80
+
For example, if `L` is 10, and `m` is 3, the explicit list of chunk lengths is `[3, 3, 3, 3]`.
81
+
82
+
- as an array that can contain two types of elements:
83
+
- an integer that explicitly denotes an edge length.
84
+
- an array that denotes a [run-length encoded](#run-length-encoding) sequence of integers,
85
+
each of which denotes an edge length.
86
+
87
+
The sum of the edge lengths MUST equal or exceed `L`. Overflowing `L` by multiple chunks is
88
+
permitted.
24
89
25
90
#### Run-length encoding
26
91
27
92
This specificiation defines a JSON representation for run-length encoded sequences.
28
93
29
-
A run-length encoded sequence of `N` repetitions of some value `V` is denoted by the length-2 JSON array `[V, N]`.
94
+
A run-length encoded sequence of `N` repetitions of some value `V` is denoted by the JSON array `[V, N]`. Both `V` and `N` MUST be integers.
30
95
31
96
For example, the sequence `[1, 1, 1, 1, 1]` becomes `[1, 5]` after applying this run-length encoding.
32
97
33
-
## Resolving
34
-
35
98
## Example
36
99
37
-
This example demonstrates 5 different ways of specifying a rectilinear chunk grid for an array with shape `(6, 6, 6, 6, 6)`.
100
+
This example demonstrates different ways of declaring the edge lengths for a rectilinear chunk grid
101
+
via the `chunk_shapes` field.
38
102
39
103
```javascript
40
104
{
@@ -45,22 +109,33 @@ This example demonstrates 5 different ways of specifying a rectilinear chunk gri
45
109
"configuration": {
46
110
"kind":"inline",
47
111
"chunk_shapes": [
48
-
[[2, 3]], // expands to [2, 2, 2]
49
-
[[1, 6]], //expands to [1, 1, 1, 1, 1, 1]
50
-
[1, [2, 1], 3], // expands to [1, 2, 3]
51
-
[[1, 3], 3], // expands to [1, 1, 1, 3]
52
-
[6] //expands to [6]
112
+
4, //integer. expands to [4, 4]
113
+
[1, 2, 3], //explicit list of edge lengths. expands to itself.
114
+
[[4, 2]], //run-length encoded. expands to [4, 4].
115
+
[[1, 3], 3], //run-length encoded and explicit list. expands to [1, 1, 1, 3]
116
+
[4, 4, 4] //explicit list with overflow chunks
53
117
]
54
118
}
55
119
}
56
120
}
57
121
```
58
122
123
+
## Compatibility with other chunk grids
124
+
125
+
A rectilinear grid is a generalization of a regular grid (a grid of regularly-spaced elements). Any
can be converted losslessly to a rectilinear chunk grid.
128
+
129
+
The simplest procedure is to copy the
130
+
`chunk_shape` field of the regular chunk grid and assign it to the `chunk_shapes` attribute of the
131
+
rectilinear chunk grid.
132
+
59
133
## Prior work
60
134
61
-
A scheme for rectilinear chunking was proposed in a [Zarr extension proposal](https://zarr.dev/zeps/draft/ZEP0003.html) (ZEP). The specification presented here builds on the ZEP 3 proposal and adapts it to the Zarr V3.
135
+
A scheme for rectilinear chunking was proposed in a
136
+
Zarr extension proposal (ZEP) called [ZEP 0003](https://zarr.dev/zeps/draft/ZEP0003.html).
137
+
The specification presented here builds on the ZEP 003 proposal and adapts it to the Zarr V3.
62
138
63
139
Key difference between this specification and ZEP 003:
64
140
- This specification adds run-length encoding for integer sequences
65
141
- This specification uses the key `"chunk_shapes"` in the `configuration` field, while ZEP 0003 uses the key `"chunk_shape"`.
66
-
- Zep 0003 defines a meaning for single-integer elements of its `chunk_shape` metadata: `"chunk_shape" : [10]` declares a sequence of chunks with length 10 repeated to match the shape of the array. While convenient, we avoid the single-integer form here because it ambiguously handles chunks at the end of an array.
0 commit comments