Processing Functions

multimodars.from_file_full(input_path_ab, input_path_cd, labels=None, step_rotation_deg=0.5, range_rotation_deg=90.0, sample_size=500, image_center=(4.5, 4.5), radius=0.5, n_points=20, write_obj=True, watertight=True, contour_types=None, output_path_ab='output/rest', output_path_cd='output/stress', output_path_ac='output/diastole', output_path_bd='output/systole', interpolation_steps=0, bruteforce=False, smooth=True, postprocessing=True)[source]

Process four intravascular imaging geometries in parallel from CSV folders.

Reads REST and STRESS acquisitions from two input folders, aligns frames within and between each cardiac phase in parallel, and writes interpolated OBJ meshes.

                    output_path_ac (Diastole: a vs. c)
            ┌──────────────────────────────────────────┐
            ▼                                          ▼
a REST diastole                      c STRESS diastole
        │  output_path_ab (Rest: a+b)        │  output_path_cd (Stress: c+d)
        ▼                                        ▼
b REST systole                       d STRESS systole
            └──────────────────────────────────────────┘
                    output_path_bd (Systole: b vs. d)

Warning

The CSV must have no header. Each row is (frame index, x-coord (mm), y-coord (mm), z-coord (mm)):

185, 5.32, 2.37, 0.0
...
Parameters:

  • input_path_ab (str) – Path to the REST input folder (contains diastolic a and systolic b CSVs).

  • input_path_cd (str) – Path to the STRESS input folder (contains diastolic c and systolic d CSVs).

  • labels (list[str] | None) – Labels for the four geometries [rest_dia, rest_sys, stress_dia, stress_sys]. Must be exactly 4 strings; if a different number is supplied the last component of each input path is used instead. Default is [].

  • step_rotation_deg (float) – Rotation step in degrees. Default is 0.5.

  • range_rotation_deg (float) – Rotation search range (±) in degrees; a range of 90° gives 180° total. Default is 90.0.

  • sample_size (int) – Number of points to downsample to during alignment. Default is 500.

  • image_center (tuple[float, float]) – Image center (x, y) in mm. Default is (4.5, 4.5).

  • radius (float) – Catheter radius in mm. Default is 0.5.

  • n_points (int) – Number of catheter points; more points increases the influence of the image center. Default is 20.

  • write_obj (bool) – Whether to write OBJ files to disk. Default is True.

  • watertight (bool) – Whether to write a watertight or shell mesh. Default is True.

  • contour_types (list[PyContourType] | None) – Contour types to export. Default is [PyContourType.Lumen, PyContourType.Catheter, PyContourType.Wall].

  • output_path_ab (str) – Output directory for REST results (pair a+b). Default is "output/rest".

  • output_path_cd (str) – Output directory for STRESS results (pair c+d). Default is "output/stress".

  • output_path_ac (str) – Output directory for DIASTOLE results (pair a+c). Default is "output/diastole".

  • output_path_bd (str) – Output directory for SYSTOLE results (pair b+d). Default is "output/systole".

  • interpolation_steps (int) – Number of interpolated meshes between phases. Default is 28.

  • bruteforce (bool) – Whether to use brute-force alignment (one comparison per step). Default is False.

  • smooth (bool) – Whether to smooth frames after alignment using a 3-point moving average. Default is True.

  • postprocessing (bool) – Whether to adjust spacing within/between geometries to equal offsets. Default is True.

Return type:

tuple[PyGeometryPair, PyGeometryPair, PyGeometryPair, PyGeometryPair, tuple[list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]]]]

Returns:

  • rest (PyGeometryPair) – Aligned geometry pair for the REST condition.

  • stress (PyGeometryPair) – Aligned geometry pair for the STRESS condition.

  • diastole (PyGeometryPair) – Aligned geometry pair for the diastolic phase.

  • systole (PyGeometryPair) – Aligned geometry pair for the systolic phase.

  • logs (tuple of list) – 4-tuple of alignment logs (logs_a, logs_b, logs_c, logs_d); each entry is a list of (id, matched_to, rel_rot_deg, total_rot_deg, tx, ty, centroid_x, centroid_y).

Examples

>>> import multimodars as mm
>>> rest, stress, dia, sys, _ = mm.from_file_full(
...     "data/ivus_rest", "data/ivus_stress"
... )
multimodars.from_file_doublepair(input_path_ab, input_path_cd, labels=None, step_rotation_deg=0.5, range_rotation_deg=90.0, sample_size=500, image_center=(4.5, 4.5), radius=0.5, n_points=20, write_obj=True, watertight=True, contour_types=None, output_path_ab='output/rest', output_path_cd='output/stress', interpolation_steps=0, bruteforce=False, smooth=True, postprocessing=True)[source]

Process two diastole/systole pairs in parallel from CSV folders.

Reads REST and STRESS acquisitions independently, aligns frames within each pair, and writes interpolated OBJ meshes.

a REST diastole                      c STRESS diastole
        │  output_path_ab (Rest: a+b)        │  output_path_cd (Stress: c+d)
        ▼                                        ▼
b REST systole                       d STRESS systole

Warning

The CSV must have no header. Each row is (frame index, x-coord (mm), y-coord (mm), z-coord (mm)):

185, 5.32, 2.37, 0.0
...
Parameters:

  • input_path_ab (str) – Path to the REST input folder (contains diastolic a and systolic b CSVs).

  • input_path_cd (str) – Path to the STRESS input folder (contains diastolic c and systolic d CSVs).

  • labels (list[str] | None) – Labels for the four geometries [rest_dia, rest_sys, stress_dia, stress_sys]. Must be exactly 4 strings; if a different number is supplied the last component of each input path is used instead. Default is [].

  • step_rotation_deg (float) – Rotation step in degrees. Default is 0.5.

  • range_rotation_deg (float) – Rotation search range (±) in degrees. Default is 90.0.

  • sample_size (int) – Number of points to downsample to. Default is 500.

  • image_center (tuple[float, float]) – Image center (x, y) in mm. Default is (4.5, 4.5).

  • radius (float) – Catheter radius in mm. Default is 0.5.

  • n_points (int) – Number of catheter points. Default is 20.

  • write_obj (bool) – Whether to write OBJ files. Default is True.

  • watertight (bool) – Whether to write a watertight or shell mesh. Default is True.

  • contour_types (list[PyContourType] | None) – Contour types to export. Default is [PyContourType.Lumen, PyContourType.Catheter, PyContourType.Wall].

  • output_path_ab (str) – Output directory for REST results (pair a+b). Default is "output/rest".

  • output_path_cd (str) – Output directory for STRESS results (pair c+d). Default is "output/stress".

  • interpolation_steps (int) – Number of interpolated meshes between phases. Default is 28.

  • bruteforce (bool) – Whether to use brute-force alignment. Default is False.

  • smooth (bool) – Whether to smooth frames after alignment. Default is True.

  • postprocessing (bool) – Whether to equalise spacing within/between geometries. Default is True.

Return type:

tuple[PyGeometryPair, PyGeometryPair, tuple[list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]]]]

Returns:

  • rest (PyGeometryPair) – Aligned geometry pair for the REST condition.

  • stress (PyGeometryPair) – Aligned geometry pair for the STRESS condition.

  • logs (tuple of list) – 4-tuple of alignment logs (logs_a, logs_b, logs_c, logs_d); each entry is a list of (id, matched_to, rel_rot_deg, total_rot_deg, tx, ty, centroid_x, centroid_y).

Examples

>>> import multimodars as mm
>>> rest, stress, _ = mm.from_file_doublepair(
...     "data/ivus_rest", "data/ivus_stress"
... )
multimodars.from_file_singlepair(input_path, labels=None, step_rotation_deg=0.5, range_rotation_deg=90.0, sample_size=500, image_center=(4.5, 4.5), radius=0.5, n_points=20, write_obj=True, watertight=True, contour_types=None, output_path='output/singlepair', interpolation_steps=0, bruteforce=False, smooth=True, postprocessing=True)[source]

Process a single diastole/systole pair from an input CSV folder.

Reads one acquisition folder, aligns the diastolic and systolic frames, and returns a single PyGeometryPair.

Pipeline:
   diastole
     │
     ▼
   systole

Warning

The CSV must have no header. Each row is (frame index, x-coord (mm), y-coord (mm), z-coord (mm)):

185, 5.32, 2.37, 0.0
...
Parameters:

  • input_path (str) – Path to the input CSV folder.

  • labels (list[str] | None) – Labels for the two geometries [diastole, systole]. Must be exactly 2 strings; if a different number is supplied the last component of the input path is used instead. Default is [].

  • step_rotation_deg (float) – Rotation step in degrees. Default is 0.5.

  • range_rotation_deg (float) – Rotation search range (±) in degrees. Default is 90.0.

  • sample_size (int) – Number of points to downsample to. Default is 500.

  • image_center (tuple[float, float]) – Image center (x, y) in mm. Default is (4.5, 4.5).

  • radius (float) – Catheter radius in mm. Default is 0.5.

  • n_points (int) – Number of catheter points. Default is 20.

  • write_obj (bool) – Whether to write OBJ files. Default is True.

  • watertight (bool) – Whether to write a watertight or shell mesh. Default is True.

  • contour_types (list[PyContourType] | None) – Contour types to export. Default is [PyContourType.Lumen, PyContourType.Catheter, PyContourType.Wall].

  • output_path (str) – Directory path to write the processed geometry. Default is "output/singlepair".

  • interpolation_steps (int) – Number of interpolated meshes. Default is 28.

  • bruteforce (bool) – Whether to use brute-force alignment. Default is False.

  • smooth (bool) – Whether to smooth frames after alignment. Default is True.

  • postprocessing (bool) – Whether to equalise spacing within/between geometries. Default is True.

Return type:

tuple[PyGeometryPair, tuple[list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]]]]

Returns:

  • pair (PyGeometryPair) – Aligned diastole/systole geometry pair.

  • logs (tuple of list) – 2-tuple of alignment logs (logs_a, logs_b); each entry is a list of (id, matched_to, rel_rot_deg, total_rot_deg, tx, ty, centroid_x, centroid_y).

Examples

>>> import multimodars as mm
>>> pair, _ = mm.from_file_singlepair("data/ivus_rest")
multimodars.from_file_single(input_path, labels=None, diastole=True, step_rotation_deg=0.5, range_rotation_deg=90.0, sample_size=500, image_center=(4.5, 4.5), radius=0.5, n_points=20, write_obj=True, watertight=True, contour_types=None, output_path='output/single', bruteforce=False, smooth=True)[source]

Process a single intravascular imaging geometry from a CSV file.

Reads one phase (diastole or systole) from an IVUS CSV file, aligns frames within the geometry, and optionally writes OBJ output.

Warning

The CSV must have no header. Each row is (frame index, x-coord (mm), y-coord (mm), z-coord (mm)).

Parameters:

  • input_path (str) – Path to the input CSV folder.

  • labels (list[str] | None) – Label for the geometry (1 string). If a different number is supplied the last component of the input path is used instead. Default is [].

  • diastole (bool) – When True process the diastolic phase; otherwise systole. Default is True.

  • step_rotation_deg (float) – Rotation step in degrees. Default is 0.5.

  • range_rotation_deg (float) – Rotation search range (±) in degrees. Default is 90.0.

  • sample_size (int) – Number of points to downsample to. Default is 500.

  • image_center (tuple[float, float]) – Image center (x, y) in mm. Default is (4.5, 4.5).

  • radius (float) – Catheter radius in mm. Default is 0.5.

  • n_points (int) – Number of catheter points. Default is 20.

  • write_obj (bool) – Whether to write OBJ files. Default is True.

  • watertight (bool) – Whether to write a watertight or shell mesh. Default is True.

  • contour_types (list[PyContourType] | None) – Contour types to export. Default is [PyContourType.Lumen, PyContourType.Catheter, PyContourType.Wall].

  • output_path (str) – Directory path to write the processed geometry. Default is "output/single".

  • bruteforce (bool) – Whether to use brute-force alignment. Default is False.

  • smooth (bool) – Whether to smooth frames after alignment. Default is True.

Return type:

tuple[PyGeometry, list[tuple[int, int, float, float, float, float, float]]]

Returns:

  • geom (PyGeometry) – Processed geometry for the chosen phase.

  • logs (list) – Alignment log entries; each entry is (id, matched_to, rel_rot_deg, total_rot_deg, tx, ty, centroid_x, centroid_y).

Examples

>>> import multimodars as mm
>>> geom, _ = mm.from_file_single("data/ivus.csv", diastole=False)
multimodars.from_array_full(input_data_a, input_data_b, input_data_c, input_data_d, step_rotation_deg=0.5, range_rotation_deg=90.0, sample_size=500, image_center=(4.5, 4.5), radius=0.5, n_points=20, write_obj=True, watertight=True, contour_types=None, output_path_ab='output/rest', output_path_cd='output/stress', output_path_ac='output/diastole', output_path_bd='output/systole', interpolation_steps=0, bruteforce=False, smooth=True, postprocessing=True)[source]

Process four PyInputData objects in parallel, aligning and interpolating between phases.

Accepts pre-loaded input data for REST diastole, REST systole, STRESS diastole, and STRESS systole, then aligns frames within and between each cardiac phase.

                    output_path_ac (Diastole: a vs. c)
            ┌──────────────────────────────────────────┐
            ▼                                          ▼
a REST diastole                      c STRESS diastole
        │  output_path_ab (Rest: a+b)        │  output_path_cd (Stress: c+d)
        ▼                                        ▼
b REST systole                       d STRESS systole
            └──────────────────────────────────────────┘
                    output_path_bd (Systole: b vs. d)
Parameters:

  • input_data_a (PyInputData) – Diastolic REST input data.

  • input_data_b (PyInputData) – Systolic REST input data.

  • input_data_c (PyInputData) – Diastolic STRESS input data.

  • input_data_d (PyInputData) – Systolic STRESS input data.

  • step_rotation_deg (float) – Rotation step in degrees. Default is 0.5.

  • range_rotation_deg (float) – Rotation search range (±) in degrees. Default is 90.0.

  • sample_size (int) – Number of points to downsample to. Default is 500.

  • image_center (tuple[float, float]) – Image center (x, y) in mm. Default is (4.5, 4.5).

  • radius (float) – Catheter radius in mm. Default is 0.5.

  • n_points (int) – Number of catheter points. Default is 20.

  • write_obj (bool) – Whether to write OBJ files. Default is True.

  • watertight (bool) – Whether to write a watertight or shell mesh. Default is True.

  • contour_types (list[PyContourType] | None) – Contour types to export. Default is [PyContourType.Lumen, PyContourType.Catheter, PyContourType.Wall].

  • output_path_ab (str) – Output directory for REST results (pair a+b). Default is "output/rest".

  • output_path_cd (str) – Output directory for STRESS results (pair c+d). Default is "output/stress".

  • output_path_ac (str) – Output directory for DIASTOLE results (pair a+c). Default is "output/diastole".

  • output_path_bd (str) – Output directory for SYSTOLE results (pair b+d). Default is "output/systole".

  • interpolation_steps (int) – Number of interpolation steps between phases. Default is 28.

  • bruteforce (bool) – Whether to use brute-force alignment. Default is False.

  • smooth (bool) – Whether to smooth frames after alignment. Default is True.

  • postprocessing (bool) – Whether to equalise spacing within/between geometries. Default is True.

Return type:

tuple[PyGeometryPair, PyGeometryPair, PyGeometryPair, PyGeometryPair, tuple[list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]]]]

Returns:

  • rest (PyGeometryPair) – Aligned geometry pair for the REST condition.

  • stress (PyGeometryPair) – Aligned geometry pair for the STRESS condition.

  • diastole (PyGeometryPair) – Aligned geometry pair for the diastolic phase.

  • systole (PyGeometryPair) – Aligned geometry pair for the systolic phase.

  • logs (tuple of list) – 4-tuple of alignment logs (logs_a, logs_b, logs_c, logs_d); each entry is a list of (id, matched_to, rel_rot_deg, total_rot_deg, tx, ty, centroid_x, centroid_y).

Examples

>>> import multimodars as mm
>>> rest, stress, dia, sys, _ = mm.from_array_full(
...     rest_dia, rest_sys, stress_dia, stress_sys
... )
multimodars.from_array_doublepair(input_data_a, input_data_b, input_data_c, input_data_d, step_rotation_deg=0.5, range_rotation_deg=90.0, sample_size=500, image_center=(4.5, 4.5), radius=0.5, n_points=20, write_obj=True, watertight=True, contour_types=None, output_path_ab='output/rest', output_path_cd='output/stress', interpolation_steps=0, bruteforce=False, smooth=True, postprocessing=True)[source]

Process two PyInputData pairs in parallel, aligning frames within each pair independently.

Accepts pre-loaded data for REST (diastole + systole) and STRESS (diastole + systole), aligns each pair independently, and writes interpolated OBJ meshes.

a REST diastole                      c STRESS diastole
        │  output_path_ab (Rest: a+b)        │  output_path_cd (Stress: c+d)
        ▼                                        ▼
b REST systole                       d STRESS systole
Parameters:

  • input_data_a (PyInputData) – Diastolic REST input data.

  • input_data_b (PyInputData) – Systolic REST input data.

  • input_data_c (PyInputData) – Diastolic STRESS input data.

  • input_data_d (PyInputData) – Systolic STRESS input data.

  • step_rotation_deg (float) – Rotation step in degrees. Default is 0.5.

  • range_rotation_deg (float) – Rotation search range (±) in degrees. Default is 90.0.

  • sample_size (int) – Number of points to downsample to. Default is 500.

  • image_center (tuple[float, float]) – Image center (x, y) in mm. Default is (4.5, 4.5).

  • radius (float) – Catheter radius in mm. Default is 0.5.

  • n_points (int) – Number of catheter points. Default is 20.

  • write_obj (bool) – Whether to write OBJ files. Default is True.

  • watertight (bool) – Whether to write a watertight or shell mesh. Default is True.

  • contour_types (list[PyContourType] | None) – Contour types to export. Default is [PyContourType.Lumen, PyContourType.Catheter, PyContourType.Wall].

  • output_path_ab (str) – Output directory for REST results (pair a+b). Default is "output/rest".

  • output_path_cd (str) – Output directory for STRESS results (pair c+d). Default is "output/stress".

  • interpolation_steps (int) – Number of interpolation steps between phases. Default is 28.

  • bruteforce (bool) – Whether to use brute-force alignment. Default is False.

  • smooth (bool) – Whether to smooth frames after alignment. Default is True.

  • postprocessing (bool) – Whether to equalise spacing within/between geometries. Default is True.

Return type:

tuple[PyGeometryPair, PyGeometryPair, tuple[list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]]]]

Returns:

  • rest (PyGeometryPair) – Aligned geometry pair for the REST condition.

  • stress (PyGeometryPair) – Aligned geometry pair for the STRESS condition.

  • logs (tuple of list) – 4-tuple of alignment logs (logs_a, logs_b, logs_c, logs_d); each entry is a list of (id, matched_to, rel_rot_deg, total_rot_deg, tx, ty, centroid_x, centroid_y).

Examples

>>> import multimodars as mm
>>> rest, stress, _ = mm.from_array_doublepair(
...     rest_dia, rest_sys, stress_dia, stress_sys
... )
multimodars.from_array_singlepair(input_data_a, input_data_b, step_rotation_deg=0.5, range_rotation_deg=90.0, sample_size=500, image_center=(4.5, 4.5), radius=0.5, n_points=20, write_obj=True, watertight=True, contour_types=None, output_path='output/singlepair', interpolation_steps=0, bruteforce=False, smooth=True, postprocessing=True)[source]

Align and interpolate between two PyInputData objects (diastole and systole).

Accepts pre-loaded diastolic and systolic input data, aligns frames between the two phases, and returns a single PyGeometryPair.

diastole ──▶ systole
Parameters:

  • input_data_a (PyInputData) – Diastolic input data.

  • input_data_b (PyInputData) – Systolic input data.

  • step_rotation_deg (float) – Rotation step in degrees. Default is 0.5.

  • range_rotation_deg (float) – Rotation search range (±) in degrees. Default is 90.0.

  • sample_size (int) – Number of points to downsample to. Default is 500.

  • image_center (tuple[float, float]) – Image center (x, y) in mm. Default is (4.5, 4.5).

  • radius (float) – Catheter radius in mm. Default is 0.5.

  • n_points (int) – Number of catheter points. Default is 20.

  • write_obj (bool) – Whether to write OBJ files. Default is True.

  • watertight (bool) – Whether to write a watertight or shell mesh. Default is True.

  • contour_types (list[PyContourType] | None) – Contour types to export. Default is [PyContourType.Lumen, PyContourType.Catheter, PyContourType.Wall].

  • output_path (str) – Directory path to write interpolated output files. Default is "output/singlepair".

  • interpolation_steps (int) – Number of interpolation steps between phases. Default is 28.

  • bruteforce (bool) – Whether to use brute-force alignment. Default is False.

  • smooth (bool) – Whether to smooth frames after alignment. Default is True.

  • postprocessing (bool) – Whether to equalise spacing within/between geometries. Default is True.

Return type:

tuple[PyGeometryPair, tuple[list[tuple[int, int, float, float, float, float, float]], list[tuple[int, int, float, float, float, float, float]]]]

Returns:

  • pair (PyGeometryPair) – Aligned diastole/systole geometry pair.

  • logs (tuple of list) – 2-tuple of alignment logs (logs_a, logs_b); each entry is a list of (id, matched_to, rel_rot_deg, total_rot_deg, tx, ty, centroid_x, centroid_y).

Examples

>>> import multimodars as mm
>>> pair, _ = mm.from_array_singlepair(rest_dia, rest_sys)
multimodars.from_array_single(input_data, step_rotation_deg=0.5, range_rotation_deg=90.0, sample_size=500, image_center=(4.5, 4.5), radius=0.5, n_points=20, write_obj=False, watertight=True, contour_types=None, output_path='output/single', bruteforce=False, smooth=True)[source]

Process a single geometry phase from a PyInputData object.

Accepts pre-loaded input data for one cardiac phase, aligns frames within the geometry, and optionally writes OBJ output.

Parameters:

  • input_data (PyInputData) – Input data for a single cardiac phase (e.g. diastolic REST).

  • step_rotation_deg (float) – Rotation step in degrees. Default is 0.5.

  • range_rotation_deg (float) – Rotation search range (±) in degrees. Default is 90.0.

  • sample_size (int) – Number of points to downsample to. Default is 500.

  • image_center (tuple[float, float]) – Image center (x, y) in mm. Default is (4.5, 4.5).

  • radius (float) – Catheter radius in mm. Default is 0.5.

  • n_points (int) – Number of catheter points. Default is 20.

  • write_obj (bool) – Whether to write OBJ files. Default is False.

  • watertight (bool) – Whether to write a watertight or shell mesh. Default is True.

  • contour_types (list[PyContourType] | None) – Contour types to export. Default is [PyContourType.Lumen, PyContourType.Catheter, PyContourType.Wall].

  • output_path (str) – Directory path to write the processed geometry. Default is "output/single".

  • bruteforce (bool) – Whether to use brute-force alignment. Default is False.

  • smooth (bool) – Whether to smooth frames after alignment. Default is True.

Return type:

tuple[PyGeometry, list[tuple[int, int, float, float, float, float, float]]]

Returns:

  • geom (PyGeometry) – Processed geometry for the chosen phase.

  • logs (list) – Alignment log entries; each entry is (id, matched_to, rel_rot_deg, total_rot_deg, tx, ty, centroid_x, centroid_y).

Examples

>>> import multimodars as mm
>>> geom, _ = mm.from_array_single(input_data)