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[Detections], path: str | 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 | PathLike) → List[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[Track], path: str | PathLike) → 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

class byotrack.icy.run.IcyRunner(icy_path: str | 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

tiemout

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

Type:

Optional[float]

run(protocol: str | PathLike, **kwargs) → 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