|
| 1 | + |
| 2 | +.. _regular-chunkgrid: |
| 3 | + |
| 4 | +================== |
| 5 | +Regular chunk grid |
| 6 | +================== |
| 7 | + |
| 8 | +Version: |
| 9 | + 1.0 |
| 10 | +Specification URI: |
| 11 | + https://zarr-specs.readthedocs.io/en/latest/v3/chunk-grids/regular-grid/ |
| 12 | +Corresponding ZEP: |
| 13 | + `ZEP0001 — Zarr specification version 3 <https://zarr.dev/zeps/draft/ZEP0001.html>`_ |
| 14 | +Issue tracking: |
| 15 | + `GitHub issues <https://github.com/zarr-developers/zarr-specs/labels/chunk-grid>`_ |
| 16 | +Suggest an edit for this spec: |
| 17 | + `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/chunk-grids/regular-grid/index.rst>`_ |
| 18 | + |
| 19 | +Copyright 2020-Present Zarr core development team. This work |
| 20 | +is licensed under a `Creative Commons Attribution 3.0 Unported License |
| 21 | +<https://creativecommons.org/licenses/by/3.0/>`_. |
| 22 | + |
| 23 | +---- |
| 24 | + |
| 25 | +Abstract |
| 26 | +======== |
| 27 | + |
| 28 | +A regular grid is a type of grid where an array is divided into chunks |
| 29 | +such that each chunk is a hyperrectangle of the same shape. The |
| 30 | +dimensionality of the grid is the same as the dimensionality of the |
| 31 | +array. Each chunk in the grid can be addressed by a tuple of positive |
| 32 | +integers (`k`, `j`, `i`, ...) corresponding to the indices of the |
| 33 | +chunk along each dimension. |
| 34 | + |
| 35 | +Description |
| 36 | +=========== |
| 37 | + |
| 38 | +The origin element of a chunk has coordinates in the array space (`k` * |
| 39 | +`dz`, `j` * `dy`, `i` * `dx`, ...) where (`dz`, `dy`, `dx`, ...) are |
| 40 | +the chunk sizes along each dimension. |
| 41 | +Thus the origin element of the chunk at grid index (0, 0, 0, |
| 42 | +...) is at coordinate (0, 0, 0, ...) in the array space, i.e., the |
| 43 | +grid is aligned with the origin of the array. If the length of any |
| 44 | +array dimension is not perfectly divisible by the chunk length along |
| 45 | +the same dimension, then the grid will overhang the edge of the array |
| 46 | +space. |
| 47 | + |
| 48 | +The shape of the chunk grid will be (ceil(`z` / `dz`), ceil(`y` / |
| 49 | +`dy`), ceil(`x` / `dx`), ...) where (`z`, `y`, `x`, ...) is the array |
| 50 | +shape, "/" is the division operator and "ceil" is the ceiling |
| 51 | +function. For example, if a 3 dimensional array has shape (10, 200, |
| 52 | +3000), and has chunk shape (5, 20, 400), then the shape of the chunk |
| 53 | +grid will be (2, 10, 8), meaning that there will be 2 chunks along the |
| 54 | +first dimension, 10 along the second dimension, and 8 along the third |
| 55 | +dimension. |
| 56 | + |
| 57 | +.. list-table:: Regular Grid Example |
| 58 | + :header-rows: 1 |
| 59 | + |
| 60 | + * - Array Shape |
| 61 | + - Chunk Shape |
| 62 | + - Chunk Grid Shape |
| 63 | + - Notes |
| 64 | + * - (10, 200, 3000) |
| 65 | + - (5, 20, 400) |
| 66 | + - (2, 10, 8) |
| 67 | + - The grid does overhang the edge of the array on the 3rd dimension. |
| 68 | + |
| 69 | +An element of an array with coordinates (`c`, `b`, `a`, ...) will |
| 70 | +occur within the chunk at grid index (`c` // `dz`, `b` // `dy`, `a` // |
| 71 | +`dx`, ...), where "//" is the floor division operator. The element |
| 72 | +will have coordinates (`c` % `dz`, `b` % `dy`, `a` % `dx`, ...) within |
| 73 | +that chunk, where "%" is the modulo operator. For example, if a |
| 74 | +3 dimensional array has shape (10, 200, 3000), and has chunk shape |
| 75 | +(5, 20, 400), then the element of the array with coordinates (7, 150, 900) |
| 76 | +is contained within the chunk at grid index (1, 7, 2) and has coordinates |
| 77 | +(2, 10, 100) within that chunk. |
| 78 | + |
| 79 | +The store key corresponding to a given grid cell is determined based on the |
| 80 | +:ref:`array-metadata-chunk-key-encoding` member of the :ref:`array-metadata`. |
| 81 | + |
| 82 | +Note that this specification does not consider the case where the |
| 83 | +chunk grid and the array space are not aligned at the origin vertices |
| 84 | +of the array and the chunk at grid index (0, 0, 0, ...). However, |
| 85 | +extensions may define variations on the regular grid type |
| 86 | +such that the grid indices may include negative integers, and the |
| 87 | +origin element of the array may occur at an arbitrary position within |
| 88 | +any chunk, which is required to allow arrays to be extended by an |
| 89 | +arbitrary length in a "negative" direction along any dimension. |
| 90 | + |
| 91 | +.. note:: Chunks at the border of an array always have the full chunk size, even when |
| 92 | + the array only covers parts of it. For example, having an array with ``"shape": [30, 30]`` and |
| 93 | + ``"chunk_shape": [16, 16]``, the chunk ``0,1`` would also contain unused values for the indices |
| 94 | + ``0-16, 30-31``. When writing such chunks it is recommended to use the current fill value |
| 95 | + for elements outside the bounds of the array. |
| 96 | + |
| 97 | + |
| 98 | + |
| 99 | +Status of this document |
| 100 | +======================= |
| 101 | + |
| 102 | +ZEP0001 was accepted on May 15th, 2023 via https://github.com/zarr-developers/zarr-specs/issues/227. |
| 103 | + |
| 104 | + |
| 105 | +Document conventions |
| 106 | +==================== |
| 107 | + |
| 108 | +Conformance requirements are expressed with a combination of |
| 109 | +descriptive assertions and [RFC2119]_ terminology. The key words |
| 110 | +"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", |
| 111 | +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative |
| 112 | +parts of this document are to be interpreted as described in |
| 113 | +[RFC2119]_. However, for readability, these words do not appear in all |
| 114 | +uppercase letters in this specification. |
| 115 | + |
| 116 | +All of the text of this specification is normative except sections |
| 117 | +explicitly marked as non-normative, examples, and notes. Examples in |
0 commit comments