Line Clip by Reference Line

Overview

This transform clips a set of lines based on where they intersect with a single, user-defined reference line.

Detailed Description

This transformation is used to shorten or trim lines at the point where they cross a specified reference line. For each line in the input data, the algorithm finds the first point of intersection with the reference line. Based on the clip_side parameter, it then keeps either the segment of the line from its start to the intersection point (KeepBase) or the segment from the intersection point to its end (KeepDistal).

If a line does not intersect the reference line, it remains unchanged in the output. This is useful for standardizing line data, for example, by trimming all lines to a common boundary.

Neuroscience Use Cases

• Standardizing Whisker Tracking Data: In neuroscience experiments involving whisker tracking, it’s often necessary to analyze the whisker’s movement relative to a fixed point, like the edge of a pole or object. This transform can clip all tracked whisker lines at the boundary of that object, ensuring that only the relevant segment of the whisker is considered for analysis.
• Analyzing Neurite Outgrowth: When studying neurite or axon growth in microscopy images, researchers might want to measure growth only up to a certain landmark or boundary. This transform can be used to clip the traced neurites at that boundary.
• Path Analysis in Behavioral Studies: In studies of animal behavior, if an animal’s path is tracked, this transform could be used to clip the path at the entrance to a specific zone or maze arm, isolating the behavior within or outside that area.

Parameters

This transform has the following parameters:

• reference_line_data_name: The key identifying the LineData object in the data manager that will be used as the reference for clipping.
• reference_frame: The specific time frame within the reference line data to use for clipping. All lines in the input data will be clipped against this single frame of the reference line.
• clip_side: Determines which part of the line to keep after clipping.
  • KeepBase: Keeps the portion of the line from its starting point to the intersection point.
  • KeepDistal: Keeps the portion of the line from the intersection point to its end point.

Example Configuration

Here is a complete example of a JSON configuration file that could be used to run this transformation. This example clips a set of lines against a reference line, keeping the base segment of each line.

[
{
    "transformations": {
        "metadata": {
            "name": "Line Clip Pipeline",
            "description": "Test line clipping on line data",
            "version": "1.0"
        },
        "steps": [
            {
                "step_id": "1",
                "transform_name": "Clip Line by Reference Line",
                "phase": "analysis",
                "input_key": "test_line",
                "output_key": "clipped_lines",
                "parameters": {
                    "reference_line_data_name": "reference_line",
                    "reference_frame": 0,
                    "clip_side": "KeepBase"
                }
            }
        ]
    }
}
]