`RectangleROI(x_pixel_range, y_pixel_range, x_range=None, y_range=None, unique_name=None, display_name=None)`

Object representing a rectangular region of interest (ROI) in an image.

This object is most simply created by the roi_creator method in the Measurement class. Alternatively it can be created manually as shown in the example below.

Physical coordinate ranges are used by default, if they are provided and can be used in the associated Measurement class. Otherwise, the obligatory pixel coordinate ranges are used as a fallback.

Example

Creating a RectangleROI instance manually:

import scipp as sc
from easyimaging.regions_of_interest import RectangleROI

roi = RectangleROI(
    x_pixel_range=(10, 50),
    y_pixel_range=(20, 80),
    x_range=(sc.scalar(0.0, unit='m'), sc.scalar(10.0, unit='m')),
    y_range=(sc.scalar(0.0, unit='m'), sc.scalar(5.0, unit='m')),
    unique_name='my_rectangle_roi',
)

Parameters:

Name	Type	Description	Default
`x_pixel_range`	`Sequence[int]`	A two-element integer sequence `[x_start, x_end]` indicating the pixel range in the x-direction.	required
`y_pixel_range`	`Sequence[int]`	A two-element integer sequence `[y_start, y_end]` indicating the pixel range in the y-direction.	required
`x_range`	`Sequence[sc.Variable] \| None`	A two-element sequence `[x_start, x_end]` of `sc.Variable` scalars with units of length, indicating the spatial coordinate range in the x-direction. Must be provided together with `y_range`.	`None`
`y_range`	`Sequence[sc.Variable] \| None`	A two-element sequence `[y_start, y_end]` of `sc.Variable` scalars with units of length, indicating the spatial coordinate range in the y-direction. Must be provided together with `x_range`.	`None`
`unique_name`	`str \| None`	A unique identifier for the ROI. Defaults to `'RectangleROI'` appended by a unique integer.	`None`
`display_name`	`str \| None`	A prettily formatted name for the ROI. Defaults to `unique_name` if not provided.	`None`

Raises:

Type	Description
`TypeError`	If `x_pixel_range` or `y_pixel_range` is not a two-element sequence of integers. If physical ranges are not two-element sequences of `sc.Variable`.
`ValueError`	If any pixel index in `x_pixel_range` or `y_pixel_range` is negative. If only one of `x_range` / `y_range` is provided. If any `sc.Variable` in `x_range` or `y_range` is not 0-dimensional (i.e., not a scalar).
`UnitError`	If any `sc.Variable` scalar in `x_range` or `y_range` does not have a unit of length.

Methods:

Name	Description
`__copy__`	Return a copy of the object.
`set_pixel_coord_range`	Set the pixel coordinate ranges defining the ROI.
`set_physical_coord_range`	Set the physical coordinate ranges defining the ROI.
`delete_physical_coord_range`	Delete the physical coordinate ranges for the ROI.
`pixel_slice`	Get a pixel index slice object corresponding to the ROI.
`slice`	Get a physical coordinate slice object corresponding to the ROI.
`to_dict`	Convert the ROI instance to a dictionary representation.
`from_dict`	Create a `RectangleROI` instance from a dictionary representation.

Attributes:

Name	Type	Description
`unique_name`	`str`	Get the unique name of the object.
`display_name`	`str`	Get a pretty display name.
`x_pixel_start`	`int`	Pixel index defining the start of the ROI in the x-direction.
`x_pixel_end`	`int`	Pixel index defining the end of the ROI in the x-direction.
`y_pixel_start`	`int`	Pixel index defining the start of the ROI in the y-direction.
`y_pixel_end`	`int`	Pixel index defining the end of the ROI in the y-direction.
`x_start`	`sc.Variable`	Physical coordinate defining the start of the ROI in the x-direction.
`x_end`	`sc.Variable`	Physical coordinate defining the end of the ROI in the x-direction.
`y_start`	`sc.Variable`	Physical coordinate defining the start of the ROI in the y-direction.
`y_end`	`sc.Variable`	Physical coordinate defining the end of the ROI in the y-direction.

Attributes

`unique_name` `property` `writable`

Get the unique name of the object.

`display_name` `property` `writable`

Get a pretty display name.

:return: The pretty display name.

`x_pixel_start` `property` `writable`

Pixel index defining the start of the ROI in the x-direction.

Parameters:

Name	Type	Description	Default
`value`	`int`	A non-negative integer pixel index.	required

Returns:

Type	Description
`int`	The x-axis pixel index defining the start of the ROI.

Raises:

Type	Description
`TypeError`	If `value` is not an integer.
`ValueError`	If `value` is negative.

`x_pixel_end` `property` `writable`

Pixel index defining the end of the ROI in the x-direction.

Parameters:

Name	Type	Description	Default
`value`	`int`	A non-negative integer pixel index.	required

Returns:

Type	Description
`int`	The x-axis pixel index defining the end of the ROI.

Raises:

Type	Description
`TypeError`	If `value` is not an integer.
`ValueError`	If `value` is negative.

`y_pixel_start` `property` `writable`

Pixel index defining the start of the ROI in the y-direction.

Parameters:

Name	Type	Description	Default
`value`	`int`	A non-negative integer pixel index.	required

Returns:

Type	Description
`int`	The y-axis pixel index defining the start of the ROI.

Raises:

Type	Description
`TypeError`	If `value` is not an integer.
`ValueError`	If `value` is negative.

`y_pixel_end` `property` `writable`

Pixel index defining the end of the ROI in the y-direction.

Parameters:

Name	Type	Description	Default
`value`	`int`	A non-negative integer pixel index.	required

Returns:

Type	Description
`int`	The y-axis pixel index defining the end of the ROI.

Raises:

Type	Description
`TypeError`	If `value` is not an integer.
`ValueError`	If `value` is negative.

`x_start` `property` `writable`

Physical coordinate defining the start of the ROI in the x-direction.

Parameters:

Name	Type	Description	Default
`value`	`sc.Variable`	A 0-dimensional `sc.Variable` scalar with a unit of length.	required

Returns:

Type	Description
`sc.Variable`	A copy of the x-axis physical coordinate defining the start of the ROI.

Raises:

Type	Description
`TypeError`	If `value` is not a `sc.Variable`.
`ValueError`	If physical coordinate ranges are not set (use `set_physical_coord_range` to set). If `value` is not a 0-dimensional `sc.Variable` (i.e., a scalar).
`UnitError`	If `value` does not have a unit of length.

`x_end` `property` `writable`

Physical coordinate defining the end of the ROI in the x-direction.

Parameters:

Name	Type	Description	Default
`value`	`sc.Variable`	A 0-dimensional `sc.Variable` scalar with a unit of length.	required

Returns:

Type	Description
`sc.Variable`	A copy of the x-axis physical coordinate defining the end of the ROI.

Raises:

Type	Description
`TypeError`	If `value` is not a `sc.Variable`.
`ValueError`	If physical coordinate ranges are not set (use `set_physical_coord_range` to set). If `value` is not a 0-dimensional `sc.Variable` (i.e., a scalar).
`UnitError`	If `value` does not have a unit of length.

`y_start` `property` `writable`

Physical coordinate defining the start of the ROI in the y-direction.

Parameters:

Name	Type	Description	Default
`value`	`sc.Variable`	A 0-dimensional `sc.Variable` scalar with a unit of length.	required

Returns:

Type	Description
`sc.Variable`	A copy of the y-axis physical coordinate defining the start of the ROI.

Raises:

Type	Description
`TypeError`	If `value` is not a `sc.Variable`.
`ValueError`	If physical coordinate ranges are not set (use `set_physical_coord_range` to set). If `value` is not a 0-dimensional `sc.Variable` (i.e., a scalar).
`UnitError`	If `value` does not have a unit of length.

`y_end` `property` `writable`

Physical coordinate defining the end of the ROI in the y-direction.

Parameters:

Name	Type	Description	Default
`value`	`sc.Variable`	A 0-dimensional `sc.Variable` scalar with a unit of length.	required

Returns:

Type	Description
`sc.Variable`	A copy of the y-axis physical coordinate defining the end of the ROI.

Raises:

Type	Description
`TypeError`	If `value` is not a `sc.Variable`.
`ValueError`	If physical coordinate ranges are not set (use `set_physical_coord_range` to set). If `value` is not a 0-dimensional `sc.Variable` (i.e., a scalar).
`UnitError`	If `value` does not have a unit of length.

Methods:

`copy()`

Return a copy of the object.

`set_pixel_coord_range(x_pixel_range, y_pixel_range)`

Set the pixel coordinate ranges defining the ROI.

Parameters:

Name	Type	Description	Default
`x_pixel_range`	`Sequence[int]`	The pixel coordinate range in the x-direction to set. Must be a two-element sequence `[x_start, x_end]` of pixel indices defining an x-axis range.	required
`y_pixel_range`	`Sequence[int]`	The pixel coordinate range in the y-direction to set. Must be a two-element sequence `[y_start, y_end]` of pixel indices defining a y-axis range.	required

Raises:

Type	Description
`TypeError`	If either argument is not a two-element sequence of integers.
`ValueError`	If any pixel index is negative.

`set_physical_coord_range(x_range, y_range)`

Set the physical coordinate ranges defining the ROI.

Parameters:

Name	Type	Description	Default
`x_range`	`Sequence[sc.Variable]`	The physical coordinate range in the x-direction to set. Must be a two-element sequence `[x_start, x_end]` of `sc.Variable` scalars with units of length	required
`y_range`	`Sequence[sc.Variable]`	The physical coordinate range in the y-direction to set. Must be a two-element sequence `[y_start, y_end]` of `sc.Variable` scalars with units of length	required

Raises:

Type	Description
`TypeError`	If either argument is not a two-element sequence of `sc.Variable`.
`ValueError`	If any `sc.Variable` in `x_range` or `y_range` is not 0-dimensional (i.e., not a scalar).
`UnitError`	If any `sc.Variable` scalar in `x_range` or `y_range` does not have a unit of length.

`delete_physical_coord_range()`

Delete the physical coordinate ranges for the ROI.

This enforces the ROI to use pixel coordinates only.

Raises:

Type	Description
`ValueError`	If physical coordinate ranges are not currently set.

`pixel_slice()`

Get a pixel index slice object corresponding to the ROI.

Returns:

Type	Description
`tuple`	Two (x,y) slice objects representing the pixel ranges of the ROI.

`slice()`

Get a physical coordinate slice object corresponding to the ROI.

Returns:

Type	Description
`tuple`	Two (x,y) slice objects representing the physical coordinate ranges of the ROI.

Raises:

Type	Description
`ValueError`	If physical coordinate ranges are not set for this ROI.

`to_dict(skip=None)`

Convert the ROI instance to a dictionary representation.

Used for saving the ROI to file.

Parameters:

Name	Type	Description	Default
`skip`	`list[str] \| None`	A list of attribute names to exclude from the output dictionary. The `'x_pixel_range'`, `'y_pixel_range'`, `'x_range'`, and `'y_range'` keys are always handled explicitly and appended regardless of this parameter.	`None`

Returns:

Type	Description
`dict`	A dictionary containing the serialised ROI data, including pixel ranges and, if available, physical coordinate ranges encoded as scipp scalar dicts.

`from_dict(input_dict)` `classmethod`

Create a RectangleROI instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
`input_dict`	`dict`	A dictionary in a format as produced by `to_dict`, containing at minimum `'x_pixel_range'` and `'y_pixel_range'` keys.	required

Returns:

Type	Description
`RectangleROI`	A new `RectangleROI` instance initialised with the data from the dictionary.

RectangleROI(x_pixel_range, y_pixel_range, x_range=None, y_range=None, unique_name=None, display_name=None)

Attributes

unique_name property writable

display_name property writable

x_pixel_start property writable

x_pixel_end property writable

y_pixel_start property writable

y_pixel_end property writable

x_start property writable

x_end property writable

y_start property writable

y_end property writable

Methods:

__copy__()

set_pixel_coord_range(x_pixel_range, y_pixel_range)

set_physical_coord_range(x_range, y_range)

delete_physical_coord_range()

pixel_slice()

slice()

to_dict(skip=None)

from_dict(input_dict) classmethod

`RectangleROI(x_pixel_range, y_pixel_range, x_range=None, y_range=None, unique_name=None, display_name=None)`

`unique_name` `property` `writable`

`display_name` `property` `writable`

`x_pixel_start` `property` `writable`

`x_pixel_end` `property` `writable`

`y_pixel_start` `property` `writable`

`y_pixel_end` `property` `writable`

`x_start` `property` `writable`

`x_end` `property` `writable`

`y_start` `property` `writable`

`y_end` `property` `writable`

`copy()`

`set_pixel_coord_range(x_pixel_range, y_pixel_range)`

`set_physical_coord_range(x_range, y_range)`

`delete_physical_coord_range()`

`pixel_slice()`

`slice()`

`to_dict(skip=None)`

`from_dict(input_dict)` `classmethod`