API Documentation

Top-Level Package

simind-python-connector connector/adaptor API.

Core

class simind_python_connector.core.config.SimulationConfig(filepath)[source]

Bases: object

SimulationConfig Class with YAML import/export capabilities

This class is designed to parse, manipulate, and save simulation configuration files. It provides easy access to configuration parameters, including index-based data, simulation flags, text variables, and associated data files. Now includes YAML export/import for better visualization and editing.

filepath

Path to the simulation configuration file.

Type:: str

index_dict

Dictionary mapping indices to parameter names for basic change data.

Type:: dict

flag_dict

Dictionary mapping indices to simulation flags.

Type:: dict

data_file_dict

Dictionary mapping indices to data file descriptions.

Type:: dict

data

List of basic change data values.

Type:: list

flags

String representing simulation flags as ‘T’ (True) or ‘F’ (False).

Type:: str

text_variables

Dictionary of text variables.

Type:: dict

data_files

Dictionary of associated data files.

Type:: dict

comment

Comment section from the configuration file.

Type:: str

__init__(filepath)[source]

Initialize the SimulationConfig instance.

Parameters:: filepath (str) – Path to the simulation configuration file.

import_smc(filepath)[source]: Parse the simulation configuration file and populate attributes.

to_yaml_dict()[source]

Convert the configuration to a structured dictionary suitable for YAML export.

Returns:: Organized configuration data
Return type:: dict

export_yaml(filepath)[source]

Export the configuration to a YAML file.

Parameters:: filepath (str) – Path for the output YAML file

import_yaml(filepath)[source]

Import configuration from a YAML file.

Parameters:: filepath (str) – Path to the input YAML file

validate_parameters()[source]

Basic parameter validation based on typical SIMIND ranges.

NOTE: This provides basic sanity checks only. Consult official SIMIND documentation for complete parameter validation rules and constraints.

get_simind_version_info()[source]: Extract version information from comment or suggest manual verification.

print_config()[source]: Print the configuration details, including comments, basic change data, flags, text variables, and data files.

get_value(index)[source]

Get the value of a parameter by its index or description.

Parameters:: index (int or str) – Parameter index or description.
Returns:: Parameter value.
Return type:: float

set_value(index, value)[source]

Set the value of a parameter by its index or description.

Parameters:

index (int or str) – Parameter index or description.
value (float) – New value for the parameter.

get_flag(index)[source]

Get the value of a simulation flag by its index or description.

Parameters:: index (int or str) – Flag index or description.
Returns:: True if the flag is set, False otherwise.
Return type:: bool

set_flag(index, value)[source]

Set the value of a simulation flag by its index or description.

Parameters:

index (int or str) – Flag index or description.
value (bool) – True to set the flag, False to clear it.

set_data_file(index, filepath)[source]

Set the path to a data file by its index.

Parameters:

index (int or str) – Data file index or description.
filepath (str) – Path to the data file.

get_data_file(index)[source]

Get the path to a data file by its index or description.

Parameters:: index (int or str) – Data file index or description.
Returns:: Path to the data file.
Return type:: str

get_comment()[source]

set_comment(comment)[source]

save_file(filepath)[source]

class simind_python_connector.core.config.RuntimeSwitches[source]

Bases: object

__init__()[source]

property combined_switch_dict

set_switch(identifier, value)[source]

print_switches()[source]

print_available_switches()[source]

Minimal SIMIND process runner used by connector-first APIs.

class simind_python_connector.core.executor.SimindExecutor[source]

Bases: object

Run SIMIND as a subprocess with optional MPI switch support.

__init__()[source]

run_simulation(output_prefix, orbit_file=None, runtime_switches=None)[source]

Return type:: None

Connectors and Adaptors

Connector/adaptor APIs.

class simind_python_connector.connectors.BaseConnector[source]

Bases: ABC

Minimal interface for all SIMIND connector styles.

abstract add_config_value(index, value)[source]

Set a SIMIND config value by index.

Return type:: None

abstract add_runtime_switch(switch, value)[source]

Set one runtime switch.

Return type:: None

set_runtime_switches(switches)[source]

Set multiple runtime switches.

Return type:: None

abstract run(*args, **kwargs)[source]

Execute simulation and return connector-native outputs.

Return type:: Any

abstract get_outputs()[source]

Return outputs from the latest successful run.

Return type:: Dict[str, Any]

abstract get_config()[source]

Return active simulation configuration.

Return type:: SimulationConfig

simind_python_connector.connectors.NumpyConnector: alias of SimindPythonConnector

class simind_python_connector.connectors.PyTomographySimindAdaptor(config_source, output_dir, output_prefix='output', photon_multiplier=1, voxel_size_mm=4.0, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

Bases: BaseConnector

SIMIND adaptor that consumes and returns PyTomography-native tensors.

Public tensor convention for this connector is object space (x, y, z). Internal SIMIND input files are written in SIMIND image order (z, y, x).

__init__(config_source, output_dir, output_prefix='output', photon_multiplier=1, voxel_size_mm=4.0, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

set_source(source)[source]

Return type:: None

set_mu_map(mu_map)[source]

Return type:: None

set_energy_windows(lower_bounds, upper_bounds, scatter_orders)[source]

Return type:: None

add_config_value(index, value)[source]

Set a SIMIND config value by index.

Return type:: None

add_runtime_switch(switch, value)[source]

Set one runtime switch.

Return type:: None

run(runtime_operator=None)[source]

Execute simulation and return connector-native outputs.

Return type:: Dict[str, Tensor]

get_outputs()[source]

Return outputs from the latest successful run.

Return type:: Dict[str, Tensor]

get_output_metadata(key)[source]

Return type:: Mapping[str, str]

get_output_header_path(key)[source]

Return type:: Path

get_total_output(window=1)[source]

Return type:: Tensor

get_scatter_output(window=1)[source]

Return type:: Tensor

get_primary_output(window=1)[source]

Return type:: Tensor

get_air_output(window=1)[source]

Return type:: Tensor

get_config()[source]: Return active simulation configuration.

static from_simind_image_axes(value)[source]

Convert SIMIND image order (z, y, x) to PyTomography (x, y, z).

Return type:: Tensor

static to_simind_image_axes(value)[source]

Convert PyTomography object order (x, y, z) to SIMIND (z, y, x).

Return type:: Tensor

class simind_python_connector.connectors.ProjectionResult(projection, header_path, data_path, metadata)[source]

Bases: object

Projection array together with the header and binary file references.

projection: ndarray

header_path: Path

data_path: Path

metadata: dict[str, str]

__init__(projection, header_path, data_path, metadata)

class simind_python_connector.connectors.RuntimeOperator(switches=<factory>, orbit_file=None)[source]

Bases: object

Runtime modifiers applied when invoking SIMIND.

switches: Dict[str, Any]

orbit_file: Union[str, PathLike[str], None] = None

__init__(switches=<factory>, orbit_file=None)

class simind_python_connector.connectors.SirfSimindAdaptor(config_source, output_dir, output_prefix='output', photon_multiplier=1, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

Bases: BaseConnector

Adaptor consuming/returning SIRF-native objects.

__init__(config_source, output_dir, output_prefix='output', photon_multiplier=1, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

set_source(source)[source]

Return type:: None

set_mu_map(mu_map)[source]

Return type:: None

set_energy_windows(lower_bounds, upper_bounds, scatter_orders)[source]

Return type:: None

add_config_value(index, value)[source]

Set a SIMIND config value by index.

Return type:: None

add_runtime_switch(switch, value)[source]

Set one runtime switch.

Return type:: None

run(runtime_operator=None)[source]

Execute simulation and return connector-native outputs.

Return type:: dict[str, Any]

get_outputs()[source]

Return outputs from the latest successful run.

Return type:: Dict[str, Any]

get_total_output(window=1)[source]

Return type:: Any

get_scatter_output(window=1)[source]

Return type:: Any

get_primary_output(window=1)[source]

Return type:: Any

get_air_output(window=1)[source]

Return type:: Any

get_penetrate_output(component)[source]

Return type:: Any

list_available_outputs()[source]

Return type:: list[str]

get_scoring_routine()[source]

Return type:: ScoringRoutine

get_config()[source]

Return active simulation configuration.

Return type:: SimulationConfig

class simind_python_connector.connectors.SimindPythonConnector(config_source, output_dir, output_prefix='output', quantization_scale=1.0)[source]

Bases: BaseConnector

Pure Python connector for SIMIND with NumPy-first outputs.

__init__(config_source, output_dir, output_prefix='output', quantization_scale=1.0)[source]

add_runtime_switch(switch, value)[source]

Set a single runtime switch.

Return type:: None

add_config_value(index, value)[source]

Set a SIMIND config value.

Return type:: None

configure_voxel_phantom(source, mu_map, voxel_size_mm=4.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

Configure voxel geometry and write source/density input files.

Return type:: tuple[Path, Path]
Returns:: Tuple of (source_file_path, density_file_path).

set_energy_windows(lower_bounds, upper_bounds, scatter_orders)[source]

Write a SIMIND window file for this connector run.

Return type:: None

run(runtime_operator=None)[source]

Run SIMIND and return projection outputs as NumPy arrays.

Return type:: dict[str, ProjectionResult]

get_outputs()[source]

Return cached outputs from the last completed run.

Return type:: dict[str, ProjectionResult]

get_config()[source]

Return active simulation configuration.

Return type:: SimulationConfig

class simind_python_connector.connectors.StirSimindAdaptor(config_source, output_dir, output_prefix='output', photon_multiplier=1, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

Bases: BaseConnector

Adaptor consuming/returning STIR-native objects.

__init__(config_source, output_dir, output_prefix='output', photon_multiplier=1, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

set_source(source)[source]

Return type:: None

set_mu_map(mu_map)[source]

Return type:: None

set_energy_windows(lower_bounds, upper_bounds, scatter_orders)[source]

Return type:: None

add_config_value(index, value)[source]

Set a SIMIND config value by index.

Return type:: None

add_runtime_switch(switch, value)[source]

Set one runtime switch.

Return type:: None

run(runtime_operator=None)[source]

Execute simulation and return connector-native outputs.

Return type:: dict[str, Any]

get_outputs()[source]

Return outputs from the latest successful run.

Return type:: Dict[str, Any]

get_total_output(window=1)[source]

Return type:: Any

get_scatter_output(window=1)[source]

Return type:: Any

get_primary_output(window=1)[source]

Return type:: Any

get_air_output(window=1)[source]

Return type:: Any

get_penetrate_output(component)[source]

Return type:: Any

list_available_outputs()[source]

Return type:: list[str]

get_scoring_routine()[source]

Return type:: ScoringRoutine

get_config()[source]

Return active simulation configuration.

Return type:: SimulationConfig

Backend-agnostic SIMIND connector returning NumPy projection outputs.

simind_python_connector.connectors.python_connector.NumpyConnector: alias of SimindPythonConnector

class simind_python_connector.connectors.python_connector.ProjectionResult(projection, header_path, data_path, metadata)[source]

Bases: object

Projection array together with the header and binary file references.

projection: ndarray

header_path: Path

data_path: Path

metadata: dict[str, str]

__init__(projection, header_path, data_path, metadata)

class simind_python_connector.connectors.python_connector.RuntimeOperator(switches=<factory>, orbit_file=None)[source]

Bases: object

Runtime modifiers applied when invoking SIMIND.

switches: Dict[str, Any]

orbit_file: Union[str, PathLike[str], None] = None

__init__(switches=<factory>, orbit_file=None)

class simind_python_connector.connectors.python_connector.SimindPythonConnector(config_source, output_dir, output_prefix='output', quantization_scale=1.0)[source]

Bases: BaseConnector

Pure Python connector for SIMIND with NumPy-first outputs.

__init__(config_source, output_dir, output_prefix='output', quantization_scale=1.0)[source]

add_runtime_switch(switch, value)[source]

Set a single runtime switch.

Return type:: None

add_config_value(index, value)[source]

Set a SIMIND config value.

Return type:: None

configure_voxel_phantom(source, mu_map, voxel_size_mm=4.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

Configure voxel geometry and write source/density input files.

Return type:: tuple[Path, Path]
Returns:: Tuple of (source_file_path, density_file_path).

set_energy_windows(lower_bounds, upper_bounds, scatter_orders)[source]

Write a SIMIND window file for this connector run.

Return type:: None

run(runtime_operator=None)[source]

Run SIMIND and return projection outputs as NumPy arrays.

Return type:: dict[str, ProjectionResult]

get_outputs()[source]

Return cached outputs from the last completed run.

Return type:: dict[str, ProjectionResult]

get_config()[source]

Return active simulation configuration.

Return type:: SimulationConfig

STIR adaptor implemented on top of the connector-first NumPy pipeline.

class simind_python_connector.connectors.stir_adaptor.StirSimindAdaptor(config_source, output_dir, output_prefix='output', photon_multiplier=1, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

Bases: BaseConnector

Adaptor consuming/returning STIR-native objects.

__init__(config_source, output_dir, output_prefix='output', photon_multiplier=1, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

set_source(source)[source]

Return type:: None

set_mu_map(mu_map)[source]

Return type:: None

set_energy_windows(lower_bounds, upper_bounds, scatter_orders)[source]

Return type:: None

add_config_value(index, value)[source]

Set a SIMIND config value by index.

Return type:: None

add_runtime_switch(switch, value)[source]

Set one runtime switch.

Return type:: None

run(runtime_operator=None)[source]

Execute simulation and return connector-native outputs.

Return type:: dict[str, Any]

get_outputs()[source]

Return outputs from the latest successful run.

Return type:: Dict[str, Any]

get_total_output(window=1)[source]

Return type:: Any

get_scatter_output(window=1)[source]

Return type:: Any

get_primary_output(window=1)[source]

Return type:: Any

get_air_output(window=1)[source]

Return type:: Any

get_penetrate_output(component)[source]

Return type:: Any

list_available_outputs()[source]

Return type:: list[str]

get_scoring_routine()[source]

Return type:: ScoringRoutine

get_config()[source]

Return active simulation configuration.

Return type:: SimulationConfig

SIRF adaptor implemented on top of the connector-first NumPy pipeline.

class simind_python_connector.connectors.sirf_adaptor.SirfSimindAdaptor(config_source, output_dir, output_prefix='output', photon_multiplier=1, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

Bases: BaseConnector

Adaptor consuming/returning SIRF-native objects.

__init__(config_source, output_dir, output_prefix='output', photon_multiplier=1, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

set_source(source)[source]

Return type:: None

set_mu_map(mu_map)[source]

Return type:: None

set_energy_windows(lower_bounds, upper_bounds, scatter_orders)[source]

Return type:: None

add_config_value(index, value)[source]

Set a SIMIND config value by index.

Return type:: None

add_runtime_switch(switch, value)[source]

Set one runtime switch.

Return type:: None

run(runtime_operator=None)[source]

Execute simulation and return connector-native outputs.

Return type:: dict[str, Any]

get_outputs()[source]

Return outputs from the latest successful run.

Return type:: Dict[str, Any]

get_total_output(window=1)[source]

Return type:: Any

get_scatter_output(window=1)[source]

Return type:: Any

get_primary_output(window=1)[source]

Return type:: Any

get_air_output(window=1)[source]

Return type:: Any

get_penetrate_output(component)[source]

Return type:: Any

list_available_outputs()[source]

Return type:: list[str]

get_scoring_routine()[source]

Return type:: ScoringRoutine

get_config()[source]

Return active simulation configuration.

Return type:: SimulationConfig

PyTomography/SIMIND adaptor.

This adaptor does not depend on SIRF/STIR objects for inputs or outputs. It accepts torch tensors, configures SIMIND directly, executes the simulation, and returns torch tensors for projection outputs.

class simind_python_connector.connectors.pytomography_adaptor.PyTomographySimindAdaptor(config_source, output_dir, output_prefix='output', photon_multiplier=1, voxel_size_mm=4.0, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

Bases: BaseConnector

SIMIND adaptor that consumes and returns PyTomography-native tensors.

Public tensor convention for this connector is object space (x, y, z). Internal SIMIND input files are written in SIMIND image order (z, y, x).

__init__(config_source, output_dir, output_prefix='output', photon_multiplier=1, voxel_size_mm=4.0, quantization_scale=1.0, scoring_routine=ScoringRoutine.SCATTWIN)[source]

set_source(source)[source]

Return type:: None

set_mu_map(mu_map)[source]

Return type:: None

set_energy_windows(lower_bounds, upper_bounds, scatter_orders)[source]

Return type:: None

add_config_value(index, value)[source]

Set a SIMIND config value by index.

Return type:: None

add_runtime_switch(switch, value)[source]

Set one runtime switch.

Return type:: None

run(runtime_operator=None)[source]

Execute simulation and return connector-native outputs.

Return type:: Dict[str, Tensor]

get_outputs()[source]

Return outputs from the latest successful run.

Return type:: Dict[str, Tensor]

get_output_metadata(key)[source]

Return type:: Mapping[str, str]

get_output_header_path(key)[source]

Return type:: Path

get_total_output(window=1)[source]

Return type:: Tensor

get_scatter_output(window=1)[source]

Return type:: Tensor

get_primary_output(window=1)[source]

Return type:: Tensor

get_air_output(window=1)[source]

Return type:: Tensor

get_config()[source]: Return active simulation configuration.

static from_simind_image_axes(value)[source]

Convert SIMIND image order (z, y, x) to PyTomography (x, y, z).

Return type:: Tensor

static to_simind_image_axes(value)[source]

Convert PyTomography object order (x, y, z) to SIMIND (z, y, x).

Return type:: Tensor

class simind_python_connector.connectors.pytomography_adaptor.RuntimeOperator(switches=<factory>, orbit_file=None)[source]

Bases: object

Runtime modifiers applied when invoking SIMIND.

switches: Dict[str, Any]

orbit_file: Union[str, PathLike[str], None] = None

__init__(switches=<factory>, orbit_file=None)

Converters

Attenuation coefficient conversion utilities.

This module provides functions to convert Hounsfield Units (HU) to attenuation coefficients and densities based on both bilinear and Schneider piecewise models.

simind_python_connector.converters.attenuation.get_package_data_path(filename)[source]: Get the path to a data file in the package.

simind_python_connector.converters.attenuation.interpolate_attenuation_coefficient(filename, energy)[source]: Interpolate attenuation coefficient from tabulated data.

simind_python_connector.converters.attenuation.get_attenuation_coefficient(material, energy, file_path=None)[source]

Get attenuation coefficient for a given material and energy.

Parameters:

material (str) – ‘water’ or ‘bone’
energy (float) – Photon energy in keV
file_path (str, optional) – Override default data file path

Returns:

Linear attenuation coefficient in cm^-1

Return type:

float

simind_python_connector.converters.attenuation.hu_to_attenuation(image_array, photon_energy, file_path=None)[source]

Convert Hounsfield Units to attenuation coefficients.

Parameters:

image_array (np.ndarray) – Array of HU values
photon_energy (float) – Photon energy in keV
file_path (str, optional) – Override default data file path

Returns:

Attenuation map in cm^-1

Return type:

np.ndarray

simind_python_connector.converters.attenuation.hu_to_density(image_array)[source]

Convert Hounsfield Units to density values.

Parameters:: image_array (np.ndarray) – Array of HU values
Returns:: Density map in g/cm^3
Return type:: np.ndarray

simind_python_connector.converters.attenuation.attenuation_to_density(attenuation_array, photon_energy, file_path=None)[source]

Convert attenuation coefficients to density values.

This is an approximate inverse of the attenuation calculation.

Parameters:

attenuation_array (np.ndarray) – Array of attenuation coefficients in cm^-1
photon_energy (float) – Photon energy in keV
file_path (str, optional) – Override default data file path

Returns:

Density map in g/cm^3

Return type:

np.ndarray

simind_python_connector.converters.attenuation.load_schneider_data()[source]

Load Schneider2000 tissue data from JSON file.

Returns:: Schneider tissue data with HU ranges and densities
Return type:: dict

simind_python_connector.converters.attenuation.hu_to_density_schneider_piecewise(image_array)[source]

Convert HU to density using exact Schneider2000 piecewise segments.

Simple step function: any HU value between HU_lo and HU_hi gets the exact density for that tissue segment.

Parameters:: image_array (np.ndarray) – Array of HU values
Returns:: Density map in g/cm^3
Return type:: np.ndarray

simind_python_connector.converters.attenuation.hu_to_density_schneider(image_array)[source]

Convert Hounsfield Units to density using Schneider2000 interpolated lookup table.

Uses the center point of each HU range for intelligent interpolation, providing smooth transitions between tissue segments.

Parameters:: image_array (np.ndarray) – Array of HU values
Returns:: Density map in g/cm^3
Return type:: np.ndarray

simind_python_connector.converters.attenuation.get_schneider_tissue_info(hu_value)[source]

Get tissue information for a specific HU value using Schneider data.

Parameters:: hu_value (float) – Hounsfield Unit value
Returns:: Tissue information including name, density, and HU range
Return type:: dict

Example

>>> info = get_schneider_tissue_info(50)
>>> print(f"Tissue: {info['name']}, Density: {info['density_g_cm3']:.3f} g/cm³")

simind_python_connector.converters.attenuation.compare_density_methods(image_array)[source]

Compare density conversion results between bilinear and Schneider methods.

Parameters:: image_array (np.ndarray) – Array of HU values
Returns:: Comparison results including density maps and statistics
Return type:: dict

DICOM to STIR conversion is handles in the AcquisitionBuilder Class

class simind_python_connector.converters.simind_to_stir.ConversionConfig(radius_scale_factor=10.0, angle_offset=180.0, default_number_format='float', ignored_patterns=None)[source]

Bases: object

Configuration for SIMIND to STIR conversion.

radius_scale_factor: float = 10.0

angle_offset: float = 180.0

default_number_format: str = 'float'

ignored_patterns: List[str] = None

__init__(radius_scale_factor=10.0, angle_offset=180.0, default_number_format='float', ignored_patterns=None)

class simind_python_connector.converters.simind_to_stir.ConversionRule[source]

Bases: object

Base class for conversion rules.

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.RadiusConversionRule(scale_factor=1.0)[source]

Bases: ConversionRule

Convert radius values with scaling.

__init__(scale_factor=1.0)[source]

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.OrbitFileRule(input_file_dir=None)[source]

Bases: ConversionRule

Process non-circular orbit file reference and insert Radii array.

__init__(input_file_dir=None)[source]

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.StartAngleConversionRule(angle_offset=180.0)[source]

Bases: ConversionRule

Convert start angle with offset.

__init__(angle_offset=180.0)[source]

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.RotationDirectionRule[source]

Bases: ConversionRule

Track rotation direction for context.

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.NumberFormatRule[source]

Bases: ConversionRule

Convert number format specifications.

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.OrbitConversionRule[source]

Bases: ConversionRule

Convert orbit specifications.

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.ImageDurationRule[source]

Bases: ConversionRule

Convert image duration to STIR format.

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.EnergyWindowRule(window_type)[source]

Bases: ConversionRule

Convert energy window specifications.

__init__(window_type)[source]

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.DataFileNameRule(override_filename=None)[source]

Bases: ConversionRule

Convert data file name references.

__init__(override_filename=None)[source]

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.IgnorePatternRule(patterns)[source]

Bases: ConversionRule

Add semicolon to ignored pattern lines.

__init__(patterns)[source]

matches(line)[source]

Check if this rule applies to the given line.

Return type:: bool

convert(line, context)[source]

Convert the line and return new line plus updated context.

Return type:: Tuple[str, Dict[str, Any]]

class simind_python_connector.converters.simind_to_stir.SimindToStirConverter(config=None)[source]

Bases: object

Enhanced SIMIND to STIR converter with configurable rules and editing capabilities.

__init__(config=None)[source]

convert_line(line, context)[source]

Convert a single line using the first matching rule.

Return type:: Tuple[str, Dict[str, Any]]

convert_file(input_filename, output_filename=None, data_file=None, return_object=False)[source]

Convert a SIMIND header file to STIR format.

Return type:: Union[AcquisitionData, AcquisitionDataInterface, None]
Returns:: Backend-agnostic acquisition data if return_object=True, None otherwise

create_penetrate_headers_from_template(h00_file, output_prefix, output_dir)[source]

Create multiple STIR headers for penetrate routine from single .h00 template.

The penetrate routine creates only one .h00 file pointing to a non-existent .a00, but multiple .bXX binary files. This method creates separate .hs headers for each .bXX file.

Parameters:

h00_file (str) – Path to the single .h00 template file from penetrate routine
output_prefix (str) – Prefix used for output files
output_dir (str) – Directory containing .bXX files

Return type:

Dict[str, AcquisitionData]

Returns:

Dictionary mapping component names to AcquisitionData objects

find_penetrate_h00_file(output_prefix, output_dir)[source]

Find the single .h00 file created by penetrate routine.

Parameters:

output_prefix (str) – Prefix used for output files
output_dir (str) – Directory containing output files

Return type:

Optional[str]

Returns:

Path to the .h00 file, or None if not found

read_parameter(filename, parameter)[source]

Read a parameter from a header file.

Return type:: Optional[str]

edit_parameter(filename, parameter, value, return_object=False)[source]

Edit a parameter in a header file.

Return type:: Optional[AcquisitionData]

add_parameter(filename, parameter, value, line_number=0, return_object=False)[source]

Add a parameter at a specific line number in an Interfile header file.

Return type:: Optional[AcquisitionData]

validate_and_fix_scaling_factors(filename, image_data, tolerance=0.1)[source]

Validate scaling factors against image voxel sizes and fix if they differ within tolerance.

Parameters:

filename (str) – Path to the header file
image_data – SIRF ImageData object to get voxel sizes from
tolerance (float) – Maximum allowed difference in mm (default 0.1mm)

Returns:

True if scaling factors were within tolerance, False if they were: corrected

Return type:

bool

add_custom_rule(rule, priority=None)[source]: Add a custom conversion rule.

validate_and_correct_radius(output_file, template_file=None, tolerance_factor=2.0)[source]

Validate radius in output file against template and correct if needed.

Parameters:

output_file (str) – Path to the output .hs file
template_file (Optional[str]) – Path to the template .hs file for comparison
tolerance_factor (float) – Factor by which radius can differ before correction

Returns:

True if radius was within tolerance, False if corrected

Return type:

bool

Utilities

simind_python_connector.utils.stir_utils.parse_sinogram(template_sinogram)[source]

Parse sinogram metadata without colliding temp files.

Accepts either a path to an interfile header or an acquisition object that exposes get_info or write. The parser reuses the shared parse_interfile_header helper for consistent behaviour.

simind_python_connector.utils.stir_utils.parse_interfile(filename)[source]

Parse STIR interfile and return dictionary of key-value pairs.

This function is kept for backward compatibility. New code should use parse_interfile_header() from interfile_parser module.

Parameters:: filename – Path to interfile file
Returns:: Dictionary of key-value pairs

simind_python_connector.utils.stir_utils.get_sirf_attenuation_from_simind(attn_filename, photopeak_energy=0.12, attn_type='mu')[source]

Reads attenuation data from simind attenuation file and returns SIRF ImageData object

Parameters:

attn_filename (string) – file name of simind attenuation file header
new_filename (string) – file name of new attenuation file header
attn_type (str, optional) – unit of attenuation binary file. Defaults to ‘mu’.

Returns:

SIRF ImageData object containing attenuation data

Return type:

image

simind_python_connector.utils.stir_utils.convert_value(val)[source]: Attempt to convert a string to int or float. Also converts a list of numbers if enclosed in { }. Otherwise, returns the stripped string.

simind_python_connector.utils.stir_utils.harmonize_stir_attributes(attributes)[source]

Apply canonical naming and derived values to raw STIR attributes.

Return type:: dict

simind_python_connector.utils.stir_utils.extract_attributes_from_stir(header_filepath)[source]

Extract attributes from a STIR header file (.hs).

Return type:: dict

simind_python_connector.utils.stir_utils.extract_attributes_from_stir_headerfile(filename)[source]

Parse a STIR header file and extract relevant attributes.

Return type:: dict

simind_python_connector.utils.stir_utils.create_stir_image(matrix_dim, voxel_size, backend=None)[source]

Create a uniform (zeros) STIR image object.

Parameters:

matrix_dim (list) – Three-element matrix size in (z, y, x) order.
voxel_size (list) – Three-element voxel size in mm for (z, y, x).
backend (Optional[str]) – Optional explicit backend ("sirf" or "stir").

Returns:

Backend image object created by STIRSPECTImageDataBuilder.

simind_python_connector.utils.stir_utils.create_stir_acqdata(proj_matrix, num_projections, pixel_size, backend=None)[source]

Create a uniform (zeros) STIR acquisition object.

Parameters:

proj_matrix (list) – Two-element projection matrix size in (radial, tangential).
num_projections (int) – Number of projection views.
pixel_size (list) – Two-element pixel size in mm for (radial, tangential).
backend (Optional[str]) – Optional explicit backend ("sirf" or "stir").

Returns:

Backend acquisition object created by STIRSPECTAcquisitionDataBuilder.

simind_python_connector.utils.stir_utils.create_simple_phantom()[source]: Create a simple cylindrical phantom with a hot sphere.

simind_python_connector.utils.stir_utils.create_attenuation_map(phantom)[source]: Create a simple attenuation map from the phantom.

exception simind_python_connector.utils.simind_utils.SimindError[source]

Bases: Exception

Base exception for SIMIND-related errors.

exception simind_python_connector.utils.simind_utils.SimindNotFoundError[source]

Bases: SimindError

Raised when SIMIND executable is not found.

simind_python_connector.utils.simind_utils.create_window_file(lower_bounds, upper_bounds, scatter_orders, output_filename='input', energy_window=None, lower_ew=None, upper_ew=None)[source]

Creates a window file for simind simulation

Parameters:

lower_bounds (list) – lower bounds of energy windows
upper_bounds (list) – upper bounds of energy windows
scatter_orders (list) – scatter orders of energy windows
output_filename (str, optional) – name of output file. Defaults to ‘input’.
energy_window (!) – energy window type can be dew or dew. Defaults to None.
lower_ew (!) – lower energy window lower and upper bounds. Defaults to None.
upper_ew (!) – upper energy window lower and upper bounds. Defaults to None.
this (! Note that dual and triple energy windows are not yet supported by)
yourself (wrapper. Please define your own energy windows and work out)

simind_python_connector.utils.io_utils.temporary_directory()[source]: Context manager for creating and cleaning up a temporary directory.

Utilities for loading Interfile projection data directly into NumPy.

class simind_python_connector.utils.interfile_numpy.InterfileArray(array, header_path, data_path, metadata)[source]

Bases: object

NumPy payload and file references parsed from an Interfile header.

array: ndarray

header_path: Path

data_path: Path

metadata: dict[str, str]

__init__(array, header_path, data_path, metadata)

simind_python_connector.utils.interfile_numpy.load_interfile_array(header_path)[source]

Load projection data referenced by an Interfile header into NumPy.

Return type:: InterfileArray