pyRadPlan.core package#

Submodules#

pyRadPlan.core.datamodel module#

Basic Model for all pyRadPlan Datastructures.

class PyRadPlanBaseModel(**data)[source]#

Bases: BaseModel

Base class for all pyRadPlan data structures.

Especially useful for structures that should be matRad compatible. Extends Pydantic’s BaseModel to use pydantic validation and serialization.

model_config#

Configuration for the model, including alias generation, population by name, arbitrary types allowed, assignment validation, and attribute creation from dictionary.

Type:

ConfigDict

Attributes:
model_extra

Get extra fields set during validation.

model_fields_set

Returns the set of fields that have been explicitly set on this model instance.

Methods

copy(*[, include, exclude, update, deep])

Returns a copy of the model.

model_construct([_fields_set])

Creates a new instance of the Model class with validated data.

model_copy(*[, update, deep])

!!! abstract "Usage Documentation"

model_dump(*[, mode, include, exclude, ...])

!!! abstract "Usage Documentation"

model_dump_json(*[, indent, ensure_ascii, ...])

!!! abstract "Usage Documentation"

model_json_schema([by_alias, ref_template, ...])

Generates a JSON schema for a model class.

model_parametrized_name(params)

Compute the class name for parametrizations of generic classes.

model_post_init(context, /)

Override this method to perform additional initialization after __init__ and model_construct.

model_rebuild(*[, force, raise_errors, ...])

Try to rebuild the pydantic-core schema for the model.

model_validate(obj, *[, strict, extra, ...])

Validate a pydantic model instance.

model_validate_json(json_data, *[, strict, ...])

!!! abstract "Usage Documentation"

model_validate_strings(obj, *[, strict, ...])

Validate the given object with string data against the Pydantic model.

to_matrad([context])

Perform matRad compatible serialization.

construct

dict

from_orm

json

parse_file

parse_obj

parse_raw

schema

schema_json

update_forward_refs

validate
model_config: ClassVar[ConfigDict] = {'alias_generator': AliasGenerator(alias=<function to_camel>, validation_alias=None, serialization_alias=None), 'arbitrary_types_allowed': True, 'from_attributes': True, 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_matrad(context='mat-file')[source]#

Perform matRad compatible serialization.

Parameters:

context (Union[str, dict]) – The context in which the datastructure should be serialized, by default ‘mat-file’.

Returns:

A datastructre compatible with matRad in the given context

Return type:

Any

Notes

Currently, the only supported context is ‘mat-file’. In the future, this could be extended to support other contexts, such as direct calling via the matlab engine or oct2py.

pyRadPlan.core.np2sitk module#

Helpers for conversion between numpy and SimpleITK.

linear_indices_to_grid_coordinates(indices, grid, index_type='numpy', dtype=<class 'numpy.float64'>)[source]#

Convert linear indices to gridcoordinates.

Parameters:

  • indices (ArrayType) – A 1D Array API conform array of linear indices where the mask is non-zero.

  • grid (Grid) – The image grid on which the indices lie.

  • index_type (Literal['numpy', 'sitk']) – The ordering of the indices. Can be ‘sitk’ for Fortran-like index ordering or ‘numpy’ for C-like index ordering. Default is ‘numpy’.

  • dtype (dtype) – The data type of the output coordinates. Default is np.float64.

Returns:

A 2D Array API conform array array of image coordinates.

Return type:

ArrayType

linear_indices_to_image_coordinates(indices, image, index_type='numpy', dtype=<class 'numpy.float64'>)[source]#

Convert linear indices to image coordinates.

Parameters:

  • indices (ArrayType) – A 1D Array API conform array of linear indices where the mask is non-zero.

  • image (Image) – The reference image on which the mask is defined.

  • index_type (Literal['numpy', 'sitk']) – The ordering of the indices. Can be ‘sitk’ for Fortran-like index ordering or ‘numpy’ for C-like index ordering. Default is ‘numpy’.

  • dtype (dtype) – The data type of the output coordinates. Default is np.float64.

Returns:

A 2D Array API conform array of image coordinates.

Return type:

ArrayType

linear_indices_to_sitk_mask(indices, ref_image, order='sitk')[source]#

Convert linear indices to a SimpleITK mask.

Parameters:

  • indices (ArrayType) – A 1D Array API conform array of linear indices where the mask is non-zero.

  • ref_image (Image) – The reference image on which the mask is defined.

  • order (str, optional) – The ordering of the indices. Can be ‘sitk’ for Fortran-like index ordering or ‘numpy’ for C-like index ordering. Default is ‘sitk’.

Returns:

A SimpleITK image mask with the indices set to non-zero.

Return type:

Image

Raises:

ValueError – If the ordering is not ‘sitk’ or ‘numpy’.

sitk_mask_to_linear_indices(mask, order='sitk')[source]#

Convert a SimpleITK mask to linear indices.

Parameters:

  • mask (Image) – The SimpleITK image mask to be converted.

  • order (str, optional) – The ordering of the indices. Can be ‘sitk’ for Fortran-like index ordering or ‘numpy’ for C-like index ordering. Default is ‘sitk’.

Returns:

A 1D numpy array of linear indices where the mask is non-zero.

Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

Raises:

ValueError – If the ordering is not ‘sitk’ or ‘numpy’.

pyRadPlan.core.resample module#

Image / Grid Resampling.

resample_image(input_image, interpolator=23, target_image=None, target_grid_spacing=None, target_grid=None, extrapolate='nearest')[source]#

Resample an sitk Image.

Use target resolution, reference image, dimensions, or Grid as input.

Parameters:

  • input_image (Image) – The input image to be resampled.

  • interpolator (sitk.InterpolatorEnum, optional) – The interpolator to use for resampling. Default is sitk.sitkBSpline.

  • extrapolate (Union[float, int, bool, Literal['nearest']]) – The value to use for extrapolation outside the image boundaries. Default is None.

  • target_image (Image) – The reference image to resample to. Default is None.

  • target_grid_spacing (tuple[float, float, float]) – The target grid spacing to resample to. Default is None.

  • target_grid (Grid) – The target grid to resample to. Default is None.

Returns:

The resampled image.

Return type:

Image

Notes

Exactly one of target_image, target_grid_spacing, or target_grid must be provided.

resample_numpy_array(input_array, reference_image=None, reference_grid=None, interpolator=23, target_image=None, target_grid_spacing=None, target_grid=None, extrapolate='nearest')[source]#

Resample a numpy grid.

Use target resolution, reference image, dimensions, or Grid as input.

We convert the numpy array to an sitk.Image, so the dimensions will be switched. More exactly, the numpy array will be index i,j,k <-> z,y,x, which will converted to j,i,k <-> y,x,z in sitk. This is to be considered when supplying the reference grid or image.

Parameters:

  • input_image (sitk.Image) – The input image to be resampled.

  • reference_image (Image) – The reference image providing spatial information of the array. Default is None. Be wary of sitk <-> numpy indexing conventions.

  • reference_grid (Grid) – The reference grid of the resampled array. Default is None. Be wary of sitk <-> numpy indexing conventions.

  • interpolator (sitk.InterpolatorEnum, optional) – The interpolator to use for resampling. Default is sitk.sitkBSpline.

  • target_image (Image) – The reference image to resample to. Default is None.

  • target_grid_spacing (tuple[float, float, float]) – The target grid spacing to resample to. Default is None.

  • target_grid (Grid) – The target grid to resample to. Default is None.

Returns:

The resampled image.

Return type:

ndarray

Notes

Exactly one of target_image, target_grid_spacing, or target_grid must be provided.

Module contents#

Core classes and functions for pyRadPlan.

class Grid(**data)[source]#

Bases: PyRadPlanBaseModel

Class representing image grids in the LPS world system.

resolution#

The resolution of the grid in the x, y, and z directions.

Type:

dict[str, float]

dimensions#

The dimensions of the grid in the x, y, and z directions.

Type:

tuple[int, int, int]

origin#

The origin of the grid in the LPS world system.

Type:

np.ndarray

direction#

The direction cosines of the grid in the LPS world system.

Type:

np.ndarray

Attributes:
model_extra

Get extra fields set during validation.

model_fields_set

Returns the set of fields that have been explicitly set on this model instance.

num_voxels

Number of voxels in the grid.

resolution_vector

Return the resolution as a vector.

x

Return the x coordinates in the LPS world system.

y

Return the y coordinates in the LPS world system.

z

Return the z coordinates in the LPS world system.

Methods

copy(*[, include, exclude, update, deep])

Returns a copy of the model.

from_sitk_image(sitk_image)

Create a Grid object from a SimpleITK image.

model_construct([_fields_set])

Creates a new instance of the Model class with validated data.

model_copy(*[, update, deep])

!!! abstract "Usage Documentation"

model_dump(*[, mode, include, exclude, ...])

!!! abstract "Usage Documentation"

model_dump_json(*[, indent, ensure_ascii, ...])

!!! abstract "Usage Documentation"

model_json_schema([by_alias, ref_template, ...])

Generates a JSON schema for a model class.

model_parametrized_name(params)

Compute the class name for parametrizations of generic classes.

model_post_init(context, /)

Override this method to perform additional initialization after __init__ and model_construct.

model_rebuild(*[, force, raise_errors, ...])

Try to rebuild the pydantic-core schema for the model.

model_validate(obj, *[, strict, extra, ...])

Validate a pydantic model instance.

model_validate_json(json_data, *[, strict, ...])

!!! abstract "Usage Documentation"

model_validate_strings(obj, *[, strict, ...])

Validate the given object with string data against the Pydantic model.

resample(target_resolution)

Create a resampled grid covering the original grid in new resolution.

to_matrad([context])

Perform matRad compatible serialization.

construct

dict

from_orm

json

parse_file

parse_obj

parse_raw

schema

schema_json

update_forward_refs

validate
dimensions: tuple[int, int, int]#
direction: NDArray[Shape[3, 3], float64]#
classmethod from_sitk_image(sitk_image)[source]#

Create a Grid object from a SimpleITK image.

Parameters:

sitk_image (Image) – The SimpleITK image to create the Grid object from.

Returns:

The Grid object created from the SimpleITK image.

Return type:

Self

model_config: ClassVar[ConfigDict] = {'alias_generator': AliasGenerator(alias=<function to_camel>, validation_alias=None, serialization_alias=None), 'arbitrary_types_allowed': True, 'from_attributes': True, 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property num_voxels: int#

Number of voxels in the grid.

origin: NDArray[Shape[3], float64]#
resample(target_resolution)[source]#

Create a resampled grid covering the original grid in new resolution.

Parameters:

target_resolution (Union[dict[str, float], ndarray, tuple[float, float, float], list[float]]) – The target resolution of the resampled grid.

Returns:

The resampled grid object.

Return type:

Self

resolution: dict[str, float]#
property resolution_vector: ndarray#

Return the resolution as a vector.

to_matrad(context='mat-file')[source]#

Perform matRad compatible serialization.

Parameters:

context (str) – The context in which the datastructure should be serialized, by default ‘mat-file’.

Returns:

A datastructre compatible with matRad in the given context

Return type:

Any

Notes

Currently, the only supported context is ‘mat-file’. In the future, this could be extended to support other contexts, such as direct calling via the matlab engine or oct2py.

property x: NDArray[Any, Any]#

Return the x coordinates in the LPS world system.

property y: NDArray[Any, Any]#

Return the y coordinates in the LPS world system.

property z: NDArray[Any, Any]#

Return the z coordinates in the LPS world system.

class PyRadPlanBaseModel(**data)[source]#

Bases: BaseModel

Base class for all pyRadPlan data structures.

Especially useful for structures that should be matRad compatible. Extends Pydantic’s BaseModel to use pydantic validation and serialization.

model_config#

Configuration for the model, including alias generation, population by name, arbitrary types allowed, assignment validation, and attribute creation from dictionary.

Type:

ConfigDict

Attributes:
model_extra

Get extra fields set during validation.

model_fields_set

Returns the set of fields that have been explicitly set on this model instance.

Methods

copy(*[, include, exclude, update, deep])

Returns a copy of the model.

model_construct([_fields_set])

Creates a new instance of the Model class with validated data.

model_copy(*[, update, deep])

!!! abstract "Usage Documentation"

model_dump(*[, mode, include, exclude, ...])

!!! abstract "Usage Documentation"

model_dump_json(*[, indent, ensure_ascii, ...])

!!! abstract "Usage Documentation"

model_json_schema([by_alias, ref_template, ...])

Generates a JSON schema for a model class.

model_parametrized_name(params)

Compute the class name for parametrizations of generic classes.

model_post_init(context, /)

Override this method to perform additional initialization after __init__ and model_construct.

model_rebuild(*[, force, raise_errors, ...])

Try to rebuild the pydantic-core schema for the model.

model_validate(obj, *[, strict, extra, ...])

Validate a pydantic model instance.

model_validate_json(json_data, *[, strict, ...])

!!! abstract "Usage Documentation"

model_validate_strings(obj, *[, strict, ...])

Validate the given object with string data against the Pydantic model.

to_matrad([context])

Perform matRad compatible serialization.

construct

dict

from_orm

json

parse_file

parse_obj

parse_raw

schema

schema_json

update_forward_refs

validate
model_config: ClassVar[ConfigDict] = {'alias_generator': AliasGenerator(alias=<function to_camel>, validation_alias=None, serialization_alias=None), 'arbitrary_types_allowed': True, 'from_attributes': True, 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_matrad(context='mat-file')[source]#

Perform matRad compatible serialization.

Parameters:

context (Union[str, dict]) – The context in which the datastructure should be serialized, by default ‘mat-file’.

Returns:

A datastructre compatible with matRad in the given context

Return type:

Any

Notes

Currently, the only supported context is ‘mat-file’. In the future, this could be extended to support other contexts, such as direct calling via the matlab engine or oct2py.

exception PyRadPlanError[source]#

Bases: Exception

Exception for errors specifically thrown by PyRadPlan.

resample_image(input_image, interpolator=23, target_image=None, target_grid_spacing=None, target_grid=None, extrapolate='nearest')[source]#

Resample an sitk Image.

Use target resolution, reference image, dimensions, or Grid as input.

Parameters:

  • input_image (Image) – The input image to be resampled.

  • interpolator (sitk.InterpolatorEnum, optional) – The interpolator to use for resampling. Default is sitk.sitkBSpline.

  • extrapolate (Union[float, int, bool, Literal['nearest']]) – The value to use for extrapolation outside the image boundaries. Default is None.

  • target_image (Image) – The reference image to resample to. Default is None.

  • target_grid_spacing (tuple[float, float, float]) – The target grid spacing to resample to. Default is None.

  • target_grid (Grid) – The target grid to resample to. Default is None.

Returns:

The resampled image.

Return type:

Image

Notes

Exactly one of target_image, target_grid_spacing, or target_grid must be provided.

resample_numpy_array(input_array, reference_image=None, reference_grid=None, interpolator=23, target_image=None, target_grid_spacing=None, target_grid=None, extrapolate='nearest')[source]#

Resample a numpy grid.

Use target resolution, reference image, dimensions, or Grid as input.

We convert the numpy array to an sitk.Image, so the dimensions will be switched. More exactly, the numpy array will be index i,j,k <-> z,y,x, which will converted to j,i,k <-> y,x,z in sitk. This is to be considered when supplying the reference grid or image.

Parameters:

  • input_image (sitk.Image) – The input image to be resampled.

  • reference_image (Image) – The reference image providing spatial information of the array. Default is None. Be wary of sitk <-> numpy indexing conventions.

  • reference_grid (Grid) – The reference grid of the resampled array. Default is None. Be wary of sitk <-> numpy indexing conventions.

  • interpolator (sitk.InterpolatorEnum, optional) – The interpolator to use for resampling. Default is sitk.sitkBSpline.

  • target_image (Image) – The reference image to resample to. Default is None.

  • target_grid_spacing (tuple[float, float, float]) – The target grid spacing to resample to. Default is None.

  • target_grid (Grid) – The target grid to resample to. Default is None.

Returns:

The resampled image.

Return type:

ndarray

Notes

Exactly one of target_image, target_grid_spacing, or target_grid must be provided.