Get rid of passing directory paths and introduce data classes for these use cases

[PolarBean]

This PR introduces some more data classes to replace instances when we would pass directory paths to functions. some examples of how this improves things are below

Segmentation Pipeline

Before

import PyNutil as pnt

atlas    = BrainGlobeAtlas("allen_mouse_25um")
alignment = pnt.read_alignment("path/to/alignment.json")

coords = pnt.seg_to_coords(
    "path/to/segmentations/",
    alignment,
    atlas,
    pixel_id=[0, 0, 0],
    object_cutoff=0,
    segmentation_format="binary",
)

After

import PyNutil as pnt

atlas     = BrainGlobeAtlas("allen_mouse_25um")
alignment = pnt.read_alignment("path/to/alignment.json")

segs   = pnt.read_segmentation_dir("path/to/segmentations/", pixel_id=[0, 0, 0])
coords = pnt.seg_to_coords(segs, alignment, atlas, object_cutoff=0)

Volume Interpolation

Before

gv, fv, dv = pnt.interpolate_volume(
    segmentation_folder="path/to/segmentations/",
    alignment_json="path/to/alignment.json",
    colour=[0, 0, 0],
    atlas=atlas,
)

pnt.save_volume_niftis(
    output_folder="path/to/output",
    interpolated_volume=gv,
    frequency_volume=fv,
    damage_volume=dv,
    atlas_volume=atlas.volume,
    voxel_size_um=atlas.voxel_size_um,
)

After

segs    = pnt.read_segmentation_dir("path/to/segmentations/", pixel_id=[0, 0, 0])
volumes = pnt.interpolate_volume(
    image_series=segs,
    registration=alignment,
    atlas=atlas,
)

pnt.save_volumes(output_folder="path/to/output", volumes=volumes, atlas=atlas)

Seperating these steps also makes it easier for users to pass arrays directly to construct segmentation objects. at the moment doing this would be a bit hacky but at least possible without writing to disk.

Im hoping that long term these data classes become useful enough as a standardised way of interacting with segmentation outputs from different tools.

[PolarBean]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Done — I merged simplify-api into this branch and resolved all merge conflicts, then pushed the follow-up fixes in 5107f06 (merge commit: 36fe540).

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• gin.g-node.org
  • Triggering command: /usr/bin/python python -m unittest tests.core.test_interpolate_volume_value_modes tests.core.test_return_orientation tests.regression.test_build_volume_from_sections tests.regression.test_damage_volume_interpolation tests.nutil_comparison.test_validator_nutil_comparison (dns block)
  • Triggering command: /usr/bin/python python -m unittest tests.core.test_interpolate_volume_value_modes tests.regression.test_build_volume_from_sections tests.regression.test_damage_volume_interpolation tests.nutil_comparison.test_validator_nutil_comparison gn/gh-gpgsign-linux-x86_64 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[IgorTatarnikov]

Looks good! Just a few comments, none are blocking.