tensorstore.overlay(layers: Sequence[TensorStore | Spec], *, read: bool | None = None, write: bool | None = None, context: Context | None = None, transaction: Transaction | None = None, rank: int | None = None, dtype: dtype | None = None, domain: IndexDomain | None = None, shape: Sequence[int] | None = None, dimension_units: Sequence[Unit | str | Real | tuple[Real, str] | None] | None = None, schema: Schema | None = None) TensorStore

Virtually overlays a sequence of TensorStore layers within a common domain.

>>> store = ts.overlay([
...     ts.array([1, 2, 3, 4], dtype=ts.uint32),
...     ts.array([5, 6, 7, 8], dtype=ts.uint32).translate_to[3]
... ])
>>> store
  'context': {'data_copy_concurrency': {}},
  'driver': 'stack',
  'dtype': 'uint32',
  'layers': [
      'array': [1, 2, 3, 4],
      'driver': 'array',
      'dtype': 'uint32',
      'transform': {'input_exclusive_max': [4], 'input_inclusive_min': [0]},
      'array': [5, 6, 7, 8],
      'driver': 'array',
      'dtype': 'uint32',
      'transform': {
        'input_exclusive_max': [7],
        'input_inclusive_min': [3],
        'output': [{'input_dimension': 0, 'offset': -3}],
  'schema': {'domain': {'exclusive_max': [7], 'inclusive_min': [0]}},
  'transform': {'input_exclusive_max': [7], 'input_inclusive_min': [0]},
>>> await store.read()
array([1, 2, 3, 5, 6, 7, 8], dtype=uint32)
layers: Sequence[TensorStore | Spec]

Sequence of layers to overlay. Later layers take precedence. If a layer is specified as a Spec rather than a TensorStore, it must have a known domain and will be opened on-demand as neneded for individual read and write operations.

read: bool | None = None

Allow read access. Defaults to True if neither read nor write is specified.

write: bool | None = None

Allow write access. Defaults to True if neither read nor write is specified.

context: Context | None = None

Shared resource context. Defaults to a new (unshared) context with default options, as returned by tensorstore.Context(). To share resources, such as cache pools, between multiple open TensorStores, you must specify a context.

transaction: Transaction | None = None

Transaction to use for opening/creating, and for subsequent operations. By default, the open is non-transactional.


To perform transactional operations using a TensorStore that was previously opened without a transaction, use TensorStore.with_transaction.

rank: int | None = None

Constrains the rank of the TensorStore. If there is an index transform, the rank constraint must match the rank of the input space.

dtype: dtype | None = None

Constrains the data type of the TensorStore. If a data type has already been set, it is an error to specify a different data type.

domain: IndexDomain | None = None

Constrains the domain of the TensorStore. If there is an existing domain, the specified domain is merged with it as follows:

  1. The rank must match the existing rank.

  2. All bounds must match, except that a finite or explicit bound is permitted to match an infinite and implicit bound, and takes precedence.

  3. If both the new and existing domain specify non-empty labels for a dimension, the labels must be equal. If only one of the domains specifies a non-empty label for a dimension, the non-empty label takes precedence.

Note that if there is an index transform, the domain must match the input space, not the output space.

shape: Sequence[int] | None = None

Constrains the shape and origin of the TensorStore. Equivalent to specifying a domain of ts.IndexDomain(shape=shape).


This option also constrains the origin of all dimensions to be zero.

dimension_units: Sequence[Unit | str | Real | tuple[Real, str] | None] | None = None

Specifies the physical units of each dimension of the domain.

The physical unit for a dimension is the physical quantity corresponding to a single index increment along each dimension.

A value of None indicates that the unit is unknown. A dimension-less quantity can be indicated by a unit of "".

schema: Schema | None = None

Additional schema constraints to merge with existing constraints.