Icy

We add support to Icy [1] software by providing I/O and a runner class that enables running protocol with Icy headless.

Utilities for inputs/outputs with icy.

byotrack.icy.io.save_detections(detections_sequence: Sequence[byotrack.Detections], path: str | os.PathLike) → None

Save a sequence of detections as valid rois for icy.

Format example (2D):

<root>
    <roi>
        <classname>plugins.kernel.roi.roi2d.ROI2DArea</classname>
        <id>30</id>
        <name>spot #0</name>
        <selected>false</selected>
        <readOnly>false</readOnly>
        <properties>None</properties>
        <color>-16711936</color>
        <stroke>2</stroke>
        <opacity>0.3</opacity>
        <showName>false</showName>
        <z>0</z>
        <t>0</t>
        <c>-1</c>
        <boundsX>238</boundsX>
        <boundsY>486</boundsY>
        <boundsW>1</boundsW>
        <boundsH>2</boundsH>
        <boolMaskData>78:5e:63:64:4:0:0:5:0:3</boolMaskData>
    </roi>
    ...
</root>

Format example (3D):

<root>
    <roi>
        <classname>plugins.kernel.roi.roi3d.ROI3DArea</classname>
        <id>30</id>
        <name>spot #0</name>
        <selected>false</selected>
        <readOnly>false</readOnly>
        <properties>None</properties>
        <color>-16711936</color>
        <stroke>2</stroke>
        <opacity>0.3</opacity>
        <showName>false</showName>
        <t>0</t>
        <c>-1</c>
        <slice>
            <classname>plugins.kernel.roi.roi2d.ROI2DArea</classname>
            ...  # See 2D format
        </slice>
        ...
    </roi>
    ...
</root>

Only needed tags are filled in the current implementation

Parameters:

• detections_sequence (Sequence[Detections]) – Detections for each frame. The frame_id attribute is not used and we rely on the position of the Detections in the sequence.

• path (str | os.PathLike) – Output path

byotrack.icy.io.load_tracks(path: str | os.PathLike) → list[byotrack.Track]

Load tracks in Icy format.

Format example:

<root>
    <trackfile version="1">
        <trackgroup description="mhtTracks-Run1">
            <track id="-1743400864">
                <detection classname="plugins.nchenouard.particletracking.DetectionSpotTrack" color="-6553856"
                    t="0" type="1" x="338.14285714285717" y="207.71428571428572" z="0"/>
                <detection classname="plugins.nchenouard.particletracking.DetectionSpotTrack" color="-6553856"
                    t="1" type="1" x="338.5" y="207.5" z="0"/>
                ...
            </track>
            ...
        </trackgroup>
    </trackfile>
</root>

For each point in each track the frame (time) and position (x, y, z) are given. An additional type precise if the detection is real or extrapolated. (Unused in ByoTrack)

Parameters:

path (str | os.PathLike) – Input path

Returns:

Parsed tracks

Return type:

list[Track]

byotrack.icy.io.save_tracks(tracks: Collection[byotrack.Track], path: str | os.PathLike, name: str = 'ByoTrack') → None

Save tracks in Icy format.

Warning

Icy do not support partial tracks (track with undefined positions). Before calling this function you should first interpolate any missing position (See ForwardBackwardInterpolater)

Format example:

<root>
    <trackfile version="1"/>
    <trackgroup description="mhtTracks-Run1">
        <track id="-1743400864">
            <detection classname="plugins.nchenouard.particletracking.DetectionSpotTrack" color="-6553856"
                t="0" type="1" x="338.14285714285717" y="207.71428571428572" z="0"/>
            <detection classname="plugins.nchenouard.particletracking.DetectionSpotTrack" color="-6553856"
                t="1" type="1" x="338.5" y="207.5" z="0"/>
            ...
        </track>
        ...
    </trackgroup>
</root>

For each point in each track the frame (t) and position (x, y, z) are given. An additional type precise if the detection is real or extrapolated. (Unused in ByoTrack).

Only needed tags are filled in the current implementation. (t, x, y, z)

Parameters:

• tracks (Collection[Track]) – Tracks to save. (Should not contain any NaN positions)

• path (str | os.PathLike) – Output path

• name (str) – Name of the tracks that will be displayed by TrackManager Default: ByoTrack

class byotrack.icy.run.IcyRunner(icy_path: str | os.PathLike | None = None, timeout: float | None = None)

Bases: object

Runs icy in headless with specified protocol and arguments.

icy_path

Path to the icy jar (Icy is called with java -jar <icy_jar>) If not given, icy is searched in the PATH

Type:

str | os.PathLike

timeout

Optional timeout in seconds for Icy protocol. Useful for EMHT which may enter an infinite loop.

Type:

float | None

run(protocol: str | os.PathLike, **kwargs: Any) → int

Runs icy with the given protocol and additional kwargs.

Parameters:

• protocol (str | os.PathLike) – Path to an Icy protocol file

• **kwargs – Additional arguments given as key=value to the cmd line

Returns:

Return code (Always 0 with Icy… but still let’s keep it)

Return type:

int