Streamline (`streamline`)¶

Terms¶

Streamline: A polyline generated by a tractography algorithm, representing an estimated fibre pathway through a diffusion MRI or synchrotron orientation field. Semantically equivalent to a polyline but with additional metadata fields specific to tractography.
GEOM_STREAMLINE: The geometry type constant "streamline".
Step size: The integration step length used during streamline propagation, stored in root .zattrs under "step_size". Common unit: mm (for MRI) or µm (for synchrotron). If the step size is uniform across all streamlines it is stored as a scalar; if variable it is stored as a per-object attribute.
Seeding strategy: The method used to generate the streamline seeds (starting points). Informational metadata stored in root .zattrs under "seeding_strategy". Common values: "wm_mask", "endpoint_roi", "random_wm", "uniform".
Propagation algorithm: The tractography integration algorithm used to generate the streamlines. Informational metadata stored under "propagation_algorithm". Common values: "deterministic", "probabilistic", "eudx", "ptt".

Introduction¶

streamline is a specialisation of polyline for MRI tractography and orientation-field tractography data. It inherits the full polyline data model (vertex sequences, object index, cross-chunk links, groupings) and adds a set of metadata fields that record how the streamlines were generated.

These metadata fields are informational — zarr-vectors-py does not use them for any computation — but they are important for scientific reproducibility and for tools that need to know the physical scale of the data (step size is required to correctly interpret arc lengths).

The streamline type also aligns closely with the TRX format’s metadata model. See TRX format comparison for a detailed mapping between TRX fields and ZVF streamline metadata.

Technical reference¶

Arrays present¶

Identical to polyline. The two types share exactly the same array schema; the distinction is in the metadata and semantic interpretation.

Array path	Required	Description
`vertices/`	Yes	Streamline vertex positions
`vertex_fragments/`	Yes	Fragment index over `vertices/` rows
`links/<delta>/`	Yes	Intra-chunk consecutive vertex pairs
`link_fragments/`	Yes (`<delta>=0`)	Fragment index over `links/0/` rows
`object_index/`	Yes	Per-object manifest blobs naming fragments
`cross_chunk_links/`	Yes*	Inter-chunk vertex connections
`attributes/<name>/`	No	Per-vertex attributes (e.g. FA, MD per point)
`object_attributes/<name>/`	No	Per-streamline attributes (e.g. mean FA, length)
`groupings/`	No	Bundle / tract group assignments

Streamline-specific root `.zattrs` keys¶

In addition to the shared ZVF root metadata, streamline stores may include:

{
  "geometry_type":       "streamline",
  "step_size":           0.5,
  "step_size_unit":      "mm",
  "seeding_strategy":    "wm_mask",
  "propagation_algorithm": "probabilistic",
  "reference_image":     "T1w_1mm_MNI152.nii.gz",
  "tractography_software": "DIPY 1.8.0",
  "min_length":          20.0,
  "max_length":          250.0,
  "length_unit":         "mm"
}

Key	Type	Description
`step_size`	`float`	Integration step length. May be a per-object attribute instead.
`step_size_unit`	`string`	Unit of `step_size`.
`seeding_strategy`	`string`	How seeds were generated. Informational.
`propagation_algorithm`	`string`	Tractography algorithm. Informational.
`reference_image`	`string`	Filename or identifier of the reference image space.
`tractography_software`	`string`	Name and version of the software.
`min_length` / `max_length`	`float`	Length filters applied during tracking. Informational.

All keys are optional. Storing them is strongly recommended for reproducibility.

Write API¶

import numpy as np
from zarr_vectors.types.polylines import write_polylines

rng = np.random.default_rng(0)
streamlines = [
    rng.normal(0, 20, (rng.integers(20, 80), 3)).cumsum(0).astype(np.float32)
    for _ in range(5000)
]

write_polylines(
    "tracts.zarrvectors",
    streamlines,
    chunk_shape=(50.0, 50.0, 50.0),
    bin_shape=(10.0, 10.0, 10.0),
    geometry_type="streamline",             # ← declares streamline type
    streamline_metadata={
        "step_size":              0.5,
        "step_size_unit":         "mm",
        "seeding_strategy":       "wm_mask",
        "propagation_algorithm":  "probabilistic",
    },
    object_attributes={
        "mean_fa": np.random.default_rng(3).uniform(0.2, 0.8, 5000).astype(np.float32),
    },
)

Ingest and export¶

TRK, TCK, and TRX converters live in the companion package zarr-vectors-tools. TRX ingest preserves dps/dpp attributes.

Variable step size¶

When streamlines in the same store have different step sizes (e.g. from different subjects or sessions), store step_size as a per-object attribute rather than a root metadata scalar:

write_polylines(
    "multi_subject.zarrvectors",
    all_streamlines,
    geometry_type="streamline",
    object_attributes={
        "step_size": per_streamline_step_sizes,   # float32, shape (n,)
    },
)

When both a root step_size and a per-object step_size attribute exist, the per-object attribute takes precedence for each streamline.

Coordinate system and physical units¶

Streamlines in MRI space are typically in mm, with coordinates aligned to the reference image affine. Synchrotron tractography uses µm. Declare the units in root .zattrs:

{
  "coordinate_system": "RAS",
  "axis_units": "mm"
}

ZVF does not store or apply affine transforms internally. If alignment to a reference image is required, apply the affine before writing or store it in custom_metadata.

Validation¶

Same rules as polyline, plus:

L2:

If step_size is present in root .zattrs, it is a positive float.
If step_size_unit is present, it is one of "mm", "um", "micrometer", "nanometer", "voxel".

Streamline (streamline)¶