Image Processors

These image processor classes each provide a contained piece of functionality for reducing or analyzing images. By stringing many image processors together, these resuable blocks of code can be applied to solve a specific image processing/machine vision situation.

`AbstractAggregateImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`AbstractSpotAnalysisImageProcessor`
`AbstractVisualizationImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`AnnotationImageProcessor`
`AverageByGroupImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`BcsLocatorImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`ConvolutionImageProcessor`
`CroppingImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`EchoImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`ExposureDetectionImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`ViewFalseColorImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`HotspotImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`LogScaleImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`NullImageSubtractionImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`PopulationStatisticsImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`SupportingImagesCollectorImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`View3dImageProcessor`	The class provides a LazyLoader for delayed importing of modules.
`ViewCrossSectionImageProcessor`	The class provides a LazyLoader for delayed importing of modules.

class opencsp.common.lib.cv.spot_analysis.image_processor.AbstractAggregateImageProcessor.AbstractAggregateImageProcessor(images_group_assigner: Callable[[SpotAnalysisOperable], int] | None = None, group_execution_trigger: Callable[[list[tuple[SpotAnalysisOperable, int]]], int | None] | None = None, name: str | None = None)

Bases: AbstractSpotAnalysisImageProcessor, ABC

Detects and collects images that are part of the same group, so that they can be acted upon all at the same time.

Each operator is assigned to an image group. Groups are determined by the images_group_assigner function. Any function with the correct signature can be used, or one of the builtin methods can be assigned. The builtin methods for this include AbstractAggregateImageProcessor.*, where “*” is one of:

group_by_brightness(): groups are determined by the brightest pixel in the image

group_by_name(): all images with the same name match are included as part of the same group

When the assigned group number for the current operator is different than for the previous operator, the group execution is triggered. _execute_aggregate() will be called for the entire group, and afterwards the group’s list will be cleared. The trigger behavior can be changed by providing a value for the group_execution_trigger parameter.

Inheriting classes need to implement the following method in liue of _execute():

def _execute_aggregate(self, group: int, operables: list, is_last: bool) -> list:

__init__(images_group_assigner: Callable[[SpotAnalysisOperable], int] | None = None, group_execution_trigger: Callable[[list[tuple[SpotAnalysisOperable, int]]], int | None] | None = None, name: str | None = None)

Parameters:

images_group_assigner (Callable[[SpotAnalysisOperable], int], optional) – The function that determines which group a given operable should be assigned to. If None, then all images will be assigned to the same group. Default is None.
group_execution_trigger (Callable[[], bool], optional) – The function that determines when a group of operators is executed on, by default group_trigger_on_change.

static group_by_brightness(intensity_to_group: dict[int, int]) → Callable[[SpotAnalysisOperable], int]

Returns a group for the given operable based on the intensity mapping and the brightest pixel in the operable’s primary image.

Intended use is as the images_group_assigner parameter to this class.

Parameters:

intensity_to_group (dict[int, int]) –

The mapping of minimum intensity for each group.

Example intensity_to_group value:

# All images with at least one pixel >= 200 will be assigned to group 2.
# Images with at least one pixel >= 125 will be assigned to group 1.
# All other images will be assigned to group 0.
intensity_to_group = {
    0: 0,
    125: 1,
    200: 2
}

static group_by_name(name_pattern: Pattern) → Callable[[SpotAnalysisOperable], int]

Returns a group for the given operable based on the groups matches “()” for the given pattern.

Intended use is as the images_group_assigner parameter to this class.

Example assignments:

pattern = re.compile(r"(foo|bar)")

foo_operable = SpotAnalaysisOperable(CacheableImage(source_path="hello_foo.png"))
food_operable = SpotAnalaysisOperable(CacheableImage(source_path="hello_food.png"))
bar_operable = SpotAnalaysisOperable(CacheableImage(source_path="hello_bar.png"))

groups: list[str] = []
images_group_assigner = group_by_name(pattern, groups)
images_group_assigner(foo_operable)  # returns 0, groups=["foo"]
images_group_assigner(food_operable) # returns 0, groups=["foo"]
images_group_assigner(bar_operable)  # returns 1, groups=["foo", "bar"]

static group_trigger_on_change() → Callable[[list[tuple[SpotAnalysisOperable, int]]], int | None]

Triggers anytime that the group assigned to the current operable is different than for the previous operable.

Intended use is as the group_execution_trigger parameter to this class.

image_groups: list[tuple[SpotAnalysisOperable, int]]: The lists of images and group assignments. The images are in the same order they were received.

class opencsp.common.lib.cv.spot_analysis.image_processor.AbstractSpotAnalysisImageProcessor.AbstractSpotAnalysisImageProcessor(name: str | None = None)

Bases: object

Class to perform one step of image processing before spot analysis is performed.

This is an abstract class. Implementations can be found in the same directory. To create a new implementation, inherit from one of the existing implementations or this class. The most basic implementation need only implement the _execute() method:

def _execute(self, operable: SpotAnalysisOperable, is_last: bool) -> list[SpotAnalysisOperable]:
    raise NotImplementedError()

__init__(name: str | None = None)

Parameters:: name (str, optional) – The name to use for this image processor instance, or None to default to the class name. By default None.

cache_images_to_disk_as_necessary(): Check memory usage and convert images to files (aka file path strings) as necessary in order to reduce memory usage.

cached: True if we’ve ever cached the processed results of this processor to disk since processing was started.

property name: str: Name of this processor

operables_in_flight: list[SpotAnalysisOperable]

For most processors, _execute() will return one resultant operable for each input operable. For these standard cases, this will contain one value during the process_operable() method, and will be empty otherwise.

Sometimes _execute() may return zero results. In this case, this value will contain all the operables passed to _execute() since the last time that _execute() returned at least one operable. These “in-flight” operables are remembered so that history can be correctly assigned to the resultant operables, once they become available.

process_images(images: list[ImageLike]) → list[ImageLike]

Processes the given images with this processor and returns 0, 1, or more than 1 resulting images.

This method is provided for convenience, to allow for use of the spot analysis image processors as if they were simple functions. The following is an example of a more standard use of an image processor:

processors = [
    EchoImageProcessor(),
    LogScaleImageProcessor(),
    ViewFalseColorImageProcessor()
]
spot_analysis = SpotAnalysis("Log Scale Images", processors)
spot_analysis.set_primary_images(images)
results = [result for result in spot_analysis]

Parameters:: images (list[CacheableImage | np.ndarray | Image.Image]) – The images to be processed.
Returns:: The resulting images after processing. Will be the same type as the first of the input images.
Return type:: list[CacheableImage | np.ndarray | Image.Image]

process_operable(input_operable: SpotAnalysisOperable, is_last: bool = False) → list[SpotAnalysisOperable]

Executes this instance’s image processing on a single given input primary image, with the supporting other images.

This method is typically called from SpotAnalysis. Other users should consider using process_images().

Parameters:

input_operable (SpotAnalysisOperable) – The primary input image to be processed, other supporting images, and any necessary data.
is_last (bool) – True if this is the last input image to be processed.

Returns:

results – Zero, one, or more than one results from running image processing.

Return type:

list[SpotAnalysisOperable]

save_to_disk: int: True to save results to the hard drive instead of holding them in memory. If False, then this is dynamically determined at runtime during image processing based on image_processors_persistant_memory_total.

class opencsp.common.lib.cv.spot_analysis.image_processor.AbstractSpotAnalysisImageProcessor.DoNothingImageProcessor(name: str | None = None): Bases: AbstractSpotAnalysisImageProcessor

class opencsp.common.lib.cv.spot_analysis.image_processor.AbstractSpotAnalysisImageProcessor.SetOnesImageProcessor(name: str | None = None): Bases: AbstractSpotAnalysisImageProcessor

opencsp.common.lib.cv.spot_analysis.image_processor.AbstractSpotAnalysisImageProcessor.image_processors_persistant_memory_total: int = 1073741824: The amount of system memory that image processors are allowed to retain as cache between calls to their ‘run()’ method. The most recently used results are prioritized for maining in memory. Default (1 GiB).

class opencsp.common.lib.cv.spot_analysis.image_processor.AbstractVisualizationImageProcessor.AbstractVisualizationImageProcessor(interactive: bool | Callable[[SpotAnalysisOperable], bool], base_image_selector: str | ImageType | None = None, name: str | None = None)

Bases: AbstractSpotAnalysisImageProcessor, ABC

An AbstractSpotAnalysisImageProcessor that is used to generate visualizations.

By convention subclasses are named “View*ImageProcessor” (their name starts with “View” and ends with “ImageProcessor”). Note that subclasses should not implement their own _execute() methods, but should instead implement num_figures, init_figure_records(), visualize_operable(), and close_figures().

The visualizations that these processors create can be used either for debugging or monitoring, depending on the value of the “interactive” initialization parameter.

VisualizationCoordinator

Certain elements of the visualization are handled by the VisualizationCoordinator, including at least:

tiled layout of visualization windows

user interaction that is common to all visualization windows

The life cycle for this class is:

- __init__()
- register_visualization_coordinator()*
- num_figures()*
- init_figure_records()*
- process()
-     _execute()
-     _get_image_for_visualizing()
-     visualize_operable()*
- close_figures()*

In the above list, one star “*” indicates that this method is called by the coordinator.

Examples

An example class that simply renders operables as an image might be implemented as:

class ViewSimpleImageProcessor(AbstractVisualizationImageProcessor):
    def __init__(self, name, interactive):
        super().__init__(name, interactive)

        self.figure_rec: RenderControlFigureRecord = None

    @property
    def num_figures(self):
        return 1

    def init_figure_records(self, render_control_fig):
        self.fig_record = fm.setup_figure(
            render_control_fig,
            rca.image(),
            equal=False,
            name=self.name,
            code_tag=f"{__file__}.init_figure_records()",
        )
        return [self.fig_record]

    def visualize_operable(self, operable, is_last):
        image = operable.primary_image.nparray
        self.fig_record.view.imshow(image)
        return [self.fig_record]

    def close_figures(self):
        with exception_tools.ignored(Exception):
            self.fig_record.close()
        self.fig_record = None

__init__(interactive: bool | Callable[[SpotAnalysisOperable], bool], base_image_selector: str | ImageType | None = None, name: str | None = None)

Parameters:

interactive (bool | Callable[[SpotAnalysisOperable], bool], optional) – If True then the spot analysis pipeline is paused until the user presses the “enter” key, by default False
base_image_selector (ImageType, optional) – Which image to draw the visualization on top of. The latest available of the given type is used. Can also be one of None, ‘Visualization’, or ‘Algorithm’. Default is the latest primary image.
name (str) – Passed through to AbstractSpotAnalysisImageProcessor.__init__()

base_image_selector: Determines the image returned from _get_image_for_visualizing(). Typically this will be one of None/ImageType.PRIMARY or ‘visualization’.

abstract close_figures(): Closes all visualization windows created by this instance.

static default_render_control_figure_for_operable(operable: SpotAnalysisOperable)

Create a default render control figure for the given operable.

This static method generates a render control figure based on the dimensions and number of channels of the primary image associated with the provided SpotAnalysisOperable. This default figure does not use tiling and does not include the typical matplotlib whitespace padding.

Parameters:: operable (SpotAnalysisOperable) – An instance of SpotAnalysisOperable containing the primary image for which the render control figure is to be created.
Returns:: A configured render control figure that can be used for visualizing the operable’s primary image.
Return type:: rcf.RenderControlFigure

Notes

The figure size is determined based on the pixel dimensions of the primary image.

property has_visualization_coordinator: bool: True if this instance is registered with a visualization coordinator. False otherwise.

abstract init_figure_records(render_control_fig: RenderControlFigure) → list[RenderControlFigureRecord]

Initializes the figure windows (via figure_management.setup_figure*) for this instance and returns the list of initialized figures. The length of this list ideally should match what was previously returned for num_figures.

Parameters:: render_control_fig (rcf.RenderControlFigure) – The render controller to use during figure setup.
Returns:: figures – The list of newly created figure windows.
Return type:: list[rcfr.RenderControlFigureRecord]

initialized_figure_records: True if init_figure_records() has been called, False otherwise.

abstract property num_figures: int: How many figure windows this instance intends to create. Must be available at all times after this instance has been initialized.

prepare_figure_records(figure_records: list[RenderControlFigureRecord], figure_shapes: list[list[int | float] | tuple | None] = ())

Clears the figure records, sets the layout margins to “tight”, and sets the figure record shape.

Parameters:

figure_records (list[rcfr.RenderControlFigureRecord]) – The figure records to be prepared.
figure_shapes (list[list[int | float] | tuple | None], optional) – The shapes of the figure records. This can either be the desired height/width of the figure in inches (if < 50), or the number of rows/columns in the figure (if > 50). The figure will be resized so that the width-to-height ratio matches this value.

register_visualization_coordinator(coordinator)

Registers the given coordinator with this visualization processor instance.

Parameters:: coordinator (VisualizationCoordinator) – The coordinator that is registering against this instance.

visualization_coordinator: VisualizationCoordinator: The coordinator registered with this instance through register_visualization_coordinator(). If None, then it is assumed that we should draw the visualization during the _execute() method.

abstract visualize_operable(operable: SpotAnalysisOperable, is_last: bool, base_image: CacheableImage) → list[CacheableImage | RenderControlFigureRecord]

Updates the figures for this instance with the data from the given operable.

The implementing visualization image processor has the option of returning visualizations as cacheable images, figure records, or a mix of both.

Parameters:

operable (SpotAnalysisOperable) – The operable to draw the visualization for.
is_last (bool) – True if this is the last operable to be drawn by this processor.
base_image (CacheableImage) – The base image on which to draw the visualization. Value is determined by base_image_selector and retrieved with _get_image_for_visualizing().

Returns:

visualizations – Visualizations from this image processor as cacheable images or as figure records. Figure records preferred. Empty list if there aren’t any.

Return type:

list[CacheableImage|rcfr.RenderControlFigureRecord]

class opencsp.common.lib.cv.spot_analysis.image_processor.AnnotationImageProcessor.AnnotationImageProcessor

Bases: AbstractSpotAnalysisImageProcessor

Draws annotations on top of the input image. The annotations drawn are those in operable.given_fiducials and operable.found_fiducials.

__init__()

Parameters:: name (str, optional) – The name to use for this image processor instance, or None to default to the class name. By default None.

class opencsp.common.lib.cv.spot_analysis.image_processor.AverageByGroupImageProcessor.AverageByGroupImageProcessor(images_group_assigner: Callable[[SpotAnalysisOperable], int] | None = None, group_execution_trigger: Callable[[list[tuple[SpotAnalysisOperable, int]]], int | None] | None = None)

Bases: AbstractAggregateImageProcessor

Averages the values from groups of images into a single image. All images must have the same shape.

See AbstractAggregateImageProcessor for more information

__init__(images_group_assigner: Callable[[SpotAnalysisOperable], int] | None = None, group_execution_trigger: Callable[[list[tuple[SpotAnalysisOperable, int]]], int | None] | None = None)

Parameters:

images_group_assigner (Callable[[SpotAnalysisOperable], int], optional) – The function that determines which group a given operable should be assigned to. If None, then all images will be assigned to the same group. Default is None.
group_execution_trigger (Callable[[], bool], optional) – The function that determines when a group of operators is executed on, by default group_trigger_on_change.

class opencsp.common.lib.cv.spot_analysis.image_processor.BcsLocatorImageProcessor.BcsLocatorImageProcessor(min_radius_px=30, max_radius_px=150, record_visualization=False)

Bases: AbstractSpotAnalysisImageProcessor

Locates the BCS by identifying a circle in the image.

It is recommended this this processor be used after ConvolutionImageProcessor(kernel=’gaussian’).

__init__(min_radius_px=30, max_radius_px=150, record_visualization=False)

Parameters:

min_radius_px (int, optional) – Minimum radius of the BSC circle, in pixels. By default 50
max_radius_px (int, optional) – Maximum radius of the BSC circle, in pixels. By default 300

class opencsp.common.lib.cv.spot_analysis.image_processor.ConvolutionImageProcessor.ConvolutionImageProcessor(kernel='gaussian', diameter=3)

Bases: AbstractSpotAnalysisImageProcessor

Convolves an image by the given kernel

Example use cases include reducing the effects of noise, and finding the average value for a larger area.

__init__(kernel='gaussian', diameter=3)

Parameters:

kernel (str, optional) – The type of kernel to apply. Options are “gaussian” or “box”. By default “gaussian”.
diameter (int, optional) – The size of the kernel to be applied, by default 3

class opencsp.common.lib.cv.spot_analysis.image_processor.CroppingImageProcessor.CroppingImageProcessor(x1x2y1y2: tuple[int, int, int, int] | Callable[[SpotAnalysisOperable], tuple[int, int, int, int]] | None = None, centered_location: tuple[int, int] | Callable[[SpotAnalysisOperable], tuple[int, int]] | None = None, width_height: tuple[int, int] | Callable[[SpotAnalysisOperable], tuple[int, int]] | None = None)

Bases: AbstractSpotAnalysisImageProcessor

Crops all input images to the given shape.

Crops to either:

a specified left/right/top/bottom region

a specified width/height around a center x/y location.

If the input image is too small, then an error will be thrown.

__init__(x1x2y1y2: tuple[int, int, int, int] | Callable[[SpotAnalysisOperable], tuple[int, int, int, int]] | None = None, centered_location: tuple[int, int] | Callable[[SpotAnalysisOperable], tuple[int, int]] | None = None, width_height: tuple[int, int] | Callable[[SpotAnalysisOperable], tuple[int, int]] | None = None): It is suggested that users call either the by_region() or by_center_and_size() methods instead of this calling this default constructor directly.

classmethod by_center_and_size(centered_location: tuple[int, int] | Callable[[SpotAnalysisOperable], tuple[int, int]], width_height: tuple[int, int] | Callable[[SpotAnalysisOperable], tuple[int, int]])

Parameters:

centered_location (tuple[int, int] | Callable[[Operable], tuple]) – The location around which to crop. If the location is too close to the edge of the image then the crop is done as close to the edge as possible while preserving the desired with and height.
width_height (tuple[int, int] | Callable[[Operable], tuple]) – The width and height to crop to.

classmethod by_region(x1x2y1y2: tuple[int, int, int, int] | Callable[[SpotAnalysisOperable], tuple])

Parameters:: x1x2y1y2 (tuple | Callable) – Either the values to crop to, or a callable to produce said values. x1: The left side of the box to crop to (inclusive). x2: The right side of the box to crop to (exclusive). y1: The top side of the box to crop to (inclusive). y2: The bottom side of the box to crop to (exclusive).

crop_around_center(operable: SpotAnalysisOperable) → SpotAnalysisOperable

Parameters:: operable (SpotAnalysisOperable) – An instance of SpotAnalysisOperable containing the primary image to be cropped and any associated image processor notes.

crop_by_bounding_box(operable: SpotAnalysisOperable) → SpotAnalysisOperable

Parameters:: operable (SpotAnalysisOperable) – An instance of SpotAnalysisOperable containing the primary image to be cropped and any associated image processor notes.

validate_center(center_xy: tuple[int, int], operable: SpotAnalysisOperable | None, debug_name: str)

validate_width_height(width_height: tuple[int, int], operable: SpotAnalysisOperable | None, debug_name: str)

validate_x1x2y1y2(x1x2y1y2: tuple[int, int, int, int], debug_name: str)

class opencsp.common.lib.cv.spot_analysis.image_processor.EchoImageProcessor.EchoImageProcessor(log_level=20, prefix='')

Bases: AbstractSpotAnalysisImageProcessor

A do-nothing processor that prints the image names to the console as they are encountered.

__init__(log_level=20, prefix='')

Parameters:: name (str, optional) – The name to use for this image processor instance, or None to default to the class name. By default None.

class opencsp.common.lib.cv.spot_analysis.image_processor.ExposureDetectionImageProcessor.ExposureDetectionImageProcessor(under_exposure_limit=0.99, under_exposure_threshold: int | float = 0.95, over_exposure_limit=0.97, max_pixel_value=255, log_level=30)

Bases: AbstractSpotAnalysisImageProcessor

A do-nothing processor that detects over and under exposure in images and adds the relavent tag to the image.

Over or under exposure is determined by the proportion of pixels that are at near the max_pixel_value threshold. If more pixels than the over exposure limit is at the maximum level, then the image is considered over exposed. If more pixels than the under exposure limit is below the under_exposure_threshold, then the image is considered under exposed.

For color images, the proportion of pixels across all color channels is used.

__init__(under_exposure_limit=0.99, under_exposure_threshold: int | float = 0.95, over_exposure_limit=0.97, max_pixel_value=255, log_level=30)

Parameters:

under_exposure_limit (float, optional) – Fraction of pixels allowed to be below the under_exposure_threshold, by default 0.99
under_exposure_threshold (int | float, optional) – If a float, then this is the fraction of the max_pixel_value that is used to determine under exposure. If an int, then this is the pixel value. For example, 0.95 and 243 will produce the same results when max_pixel_value is 255. By default 0.95
over_exposure_limit (float, optional) – Fraction of pixels that should be below the maximum value, by default 0.97
max_pixel_value (int, optional) – The maximum possible value of the pixels, by default 255 to match uint8 images
log_level (int, optional) – The level to print out warnings at, by default log.WARN

class opencsp.common.lib.cv.spot_analysis.image_processor.ViewFalseColorImageProcessor.ViewFalseColorImageProcessor(map_type='human', opencv_map=2, interactive: bool | Callable[[SpotAnalysisOperable], bool] = False, base_image_selector: str | ImageType | None = None)

Bases: AbstractVisualizationImageProcessor

Image processor to produce color gradient images from grayscale images, for better contrast and legibility by humans.

__init__(map_type='human', opencv_map=2, interactive: bool | Callable[[SpotAnalysisOperable], bool] = False, base_image_selector: str | ImageType | None = None)

Parameters:

map_type (str, optional) – This determines the number of visible colors. Options are ‘opencv’ (256), ‘human’ (893), ‘large’ (1530). Large has the most possible colors. Human reduces the number of greens and reds, since those are difficult to discern. Default is ‘human’.
opencv_map (opencv map type, optional) – Which color pallete to use with the OpenCV color mapper. Default is cv2.COLORMAP_JET.

apply_mapping_jet(operable: SpotAnalysisOperable, image: CacheableImage) → CacheableImage

Updates the primary image with a false color map. Opencv maps can represent 256 different grayscale colors and only takes ~0.007s for a 1626 x 1236 pixel image.

Parameters:

operable (SpotAnalysisOperable) – The operable that the given image came from.
image (CacheableImage) – The image to apply the false color to.

Returns:

A new image with RGB color channels and the input grayscale values mapped to the jet color scheme.

Return type:

image

apply_mapping_jet_custom(operable: SpotAnalysisOperable, image: CacheableImage) → CacheableImage

Updates the primary image with a false color map (‘human’ or ‘large’). This has a much larger range of colors that get applied but is also much slower than the OpenCV version.

See also image_reshapers.false_color_reshaper()

Parameters:

operable (SpotAnalysisOperable) – The operable that the given image came from.
image (CacheableImage) – The image to apply the false color to.

Returns:

A new image with RGB color channels and the input grayscale values mapped to the jet color scheme.

Return type:

image

close_figures(): Closes all visualization windows created by this instance.

init_figure_records(render_control_fig: RenderControlFigure) → list[RenderControlFigureRecord]

Initializes the figure windows (via figure_management.setup_figure*) for this instance and returns the list of initialized figures. The length of this list ideally should match what was previously returned for num_figures.

Parameters:: render_control_fig (rcf.RenderControlFigure) – The render controller to use during figure setup.
Returns:: figures – The list of newly created figure windows.
Return type:: list[rcfr.RenderControlFigureRecord]

property num_figures: int: How many figure windows this instance intends to create. Must be available at all times after this instance has been initialized.

visualize_operable(operable: SpotAnalysisOperable, is_last: bool, base_image: CacheableImage) → list[CacheableImage | RenderControlFigureRecord]

Updates the figures for this instance with the data from the given operable.

The implementing visualization image processor has the option of returning visualizations as cacheable images, figure records, or a mix of both.

Parameters:

operable (SpotAnalysisOperable) – The operable to draw the visualization for.
is_last (bool) – True if this is the last operable to be drawn by this processor.
base_image (CacheableImage) – The base image on which to draw the visualization. Value is determined by base_image_selector and retrieved with _get_image_for_visualizing().

Returns:

visualizations – Visualizations from this image processor as cacheable images or as figure records. Figure records preferred. Empty list if there aren’t any.

Return type:

list[CacheableImage|rcfr.RenderControlFigureRecord]

class opencsp.common.lib.cv.spot_analysis.image_processor.HotspotImageProcessor.HotspotImageProcessor(desired_shape: int | tuple, style: RenderControlPointSeq | None = None, draw_debug_view: bool | Callable[[SpotAnalysisOperable], bool] = False, record_visualization=False, record_debug_view: bool | int = False)

Bases: AbstractSpotAnalysisImageProcessor

Adds an annotation marker to images to indicate at which pixel the brightest part of the image is.

We want to be able to determine the point of peak intensity within an image, within a certain window size. The window size is chosen manually and should reflect the level of uncertainty in heliostat pointing. A local minimum filter is applied to find the overall hottest part of the image. The filter starts large and gradually shrinks until it fits the desired window size.

Note: this is NOT the same as the brightest pixel, which can be trivially found with np.max(image). Likewise, it is NOT the centroid.

__init__(desired_shape: int | tuple, style: RenderControlPointSeq | None = None, draw_debug_view: bool | Callable[[SpotAnalysisOperable], bool] = False, record_visualization=False, record_debug_view: bool | int = False)

Parameters:

desired_shape (int | tuple, optional) – The window size used to determine the brightest area, in pixels. If an integer, then the same value is used for all dimensions. If a tuple, then it must have the same number of values as dimensions in the image. Must be odd.
style (rcps.RenderControlPointSeq, optional) – The style used to render the hotspot point with View3d.draw_pq_list(). By default (‘x’, red).
draw_debug_view (bool | Callable[[SpotAnalysisOperable], bool], optional) – True to show the iterative process used to converge on the hotspot. By default False.
record_visualization (bool) – True to add the visualization of the hotspot on top of the input image to the visualization images. By default False.
record_debug_view (bool | int, optional) – True to record the debug views to the visualization images. If an integer, than up to that number of debug images will be recorded. If draw_debug_view is False then this option does nothing.

iteration_reduction_px: int = 10: The amount to subtract from the previous search shape by for each iteration

starting_max_factor: float = 2: The factor to multiple desired_shape by to start the search

The class provides a LazyLoader for delayed importing of modules. It allows for lazy loading of modules until they are actually needed, which can help improve performance by reducing load times in most cases.

class opencsp.common.lib.cv.spot_analysis.image_processor.NullImageSubtractionImageProcessor.NullImageSubtractionImageProcessor(default_null_image: ndarray | None = None)

Bases: AbstractSpotAnalysisImageProcessor

Subtracts the NULL supporting image from the primary image, if there is an associated NULL image.

Suggested use is by either assigning supporting images manually, or by using the SupportingImagesCollectorImageProcessor.

__init__(default_null_image: ndarray | None = None)

Parameters:: name (str, optional) – The name to use for this image processor instance, or None to default to the class name. By default None.

class opencsp.common.lib.cv.spot_analysis.image_processor.PopulationStatisticsImageProcessor.PopulationStatisticsImageProcessor(min_pop_size=1, target_rolling_window_size=1, initial_min: int | None = None, initial_max: int | None = None)

Bases: AbstractSpotAnalysisImageProcessor

Generates statistics for groups of images.

A group of images is held until enough have been seen to generate statistics off of. Once the required number of images has been reached, then images will start being released one at a time with the statistics for the group up until that point.

Some use cases for this class could include automatically determining the maximum pixel value during streaming to select an appropriate bit depth, using the rolling average for exposure calibration, or leveling all images by subtracting the gloal pixel minimum.

__init__(min_pop_size=1, target_rolling_window_size=1, initial_min: int | None = None, initial_max: int | None = None)

Parameters:

min_pop_size (int, optional) – The minimum number of images that must be seen before any images (and their statistics) are released to the next image processor. -1 to wait for all images. By default 1
target_rolling_window_size (int, optional) – Number of images used to determine rolling averages. The first N-1 images are not held back while waiting for this target. By default 1
initial_min (int, optional) – Initial value used to estimate the population minimum. If None, then the minimum of the first image seen is used. By default None
initial_max (int, optional) – Initial value used to estimage the population maximum. If None, then the maximum of the first image seen is used. By default None

curr_stats: SpotAnalysisPopulationStatistics: The current statistics, which get updated with each image seen. None if min_pop_size hasn’t been met yet.

initial_operables: list[SpotAnalysisOperable]: The initial operables gathered while waiting for min_pop_size.

min_pop_size: The number of operables that must be analyzed before allowing any through for further processing. -1 if all images are required to be analyzed before continuing.

rolling_window_operables: list[SpotAnalysisOperable]: The last N operables seen, for the purpose of gathering statistics on a rolling window of imagess.

target_rolling_window_size: The number of operables that are held for calculating rolling average statistics. Truncated to be <= min_pop_size.

class opencsp.common.lib.cv.spot_analysis.image_processor.SupportingImagesCollectorImageProcessor.SupportingImagesCollectorImageProcessor(supporting_images_map: dict[ImageType, Callable[[SpotAnalysisOperable, dict[ImageType, SpotAnalysisOperable]], bool]])

Bases: AbstractSpotAnalysisImageProcessor

Collects primary and supporting images together from a stream of mixed images.

The basic algorithm is pretty simple:

catagorize images based on the given supporting_images_map

if the image type isn’t already in the internal list, then add it and go back to step 1

collect all images in the internal list together as a single operable

clear the internal list

start a new internal list with the current image

return the new operable, go back to step 1

Example usage:

supporting_images_map = {
    ImageType.PRIMARY: lambda operable, operables: "off" not in operable.get_primary_path_nameext(),
    ImageType.NULL: lambda operable, operables: "off" in operable.get_primary_path_nameext(),
}
collector_processor = SupportingImagesCollectorImageProcessor(supporting_images_map)

__init__(supporting_images_map: dict[ImageType, Callable[[SpotAnalysisOperable, dict[ImageType, SpotAnalysisOperable]], bool]])

Parameters:: supporting_images_map (dict[ ImageType, Callable[[SpotAnalysisOperable, dict[ImageType, SpotAnalysisOperable]], bool] ]) – How to categorize images. If supporting_images_map[ImageType.PRIMARY](operable, curr_mapped_images) == True then the image will be assigned as a primary image. Otherwise it will be grouped with another primary image as a supporting image.

class opencsp.common.lib.cv.spot_analysis.image_processor.View3dImageProcessor.View3dImageProcessor(label: str | RenderControlAxis = 'Light Intensity', max_resolution: tuple[int, int] | None = None, crop_to_threshold: int | None = None, interactive: bool | Callable[[SpotAnalysisOperable], bool] = False, base_image_selector: str | ImageType | None = None)

Bases: AbstractVisualizationImageProcessor

Interprets the current image as a 3D surface plot and either displays it, or if interactive it displays the surface and waits on the next press of the “enter” key.

Parameters:

label (str | rca.RenderControlAxis, optional) – The label to use for the window title, by default ‘Light Intensity’
max_resolution (tuple[int, int] | None, optional) – Limits the resolution along the x and y axes to the given values. No limit if None. By default None.
crop_to_threshold (int | None, optional) – Crops the image on the x and y axis to the first/last value >= the given threshold. None to not crop the image. Useful when trying to inspect hot spots on images with very concentrated values. By default None.

close_figures(): Closes all visualization windows created by this instance.

init_figure_records(render_control_fig: RenderControlFigure) → list[RenderControlFigureRecord]

Initializes the figure windows (via figure_management.setup_figure*) for this instance and returns the list of initialized figures. The length of this list ideally should match what was previously returned for num_figures.

Parameters:: render_control_fig (rcf.RenderControlFigure) – The render controller to use during figure setup.
Returns:: figures – The list of newly created figure windows.
Return type:: list[rcfr.RenderControlFigureRecord]

property num_figures: int: How many figure windows this instance intends to create. Must be available at all times after this instance has been initialized.

visualize_operable(operable: SpotAnalysisOperable, is_last: bool, base_image: CacheableImage) → list[CacheableImage | RenderControlFigureRecord]

Updates the figures for this instance with the data from the given operable.

The implementing visualization image processor has the option of returning visualizations as cacheable images, figure records, or a mix of both.

Parameters:

operable (SpotAnalysisOperable) – The operable to draw the visualization for.
is_last (bool) – True if this is the last operable to be drawn by this processor.
base_image (CacheableImage) – The base image on which to draw the visualization. Value is determined by base_image_selector and retrieved with _get_image_for_visualizing().

Returns:

visualizations – Visualizations from this image processor as cacheable images or as figure records. Figure records preferred. Empty list if there aren’t any.

Return type:

list[CacheableImage|rcfr.RenderControlFigureRecord]

class opencsp.common.lib.cv.spot_analysis.image_processor.ViewCrossSectionImageProcessor.ViewCrossSectionImageProcessor(cross_section_location: Callable[[SpotAnalysisOperable], tuple[int, int]] | tuple[int, int] | str | PixelOfInterest | None = None, single_plot: bool = True, crop_to_threshold: int | None = None, y_range: tuple[int, int] | None = None, plot_title: str | Callable[[SpotAnalysisOperable], str] | Literal[False] | None = None, interactive: bool | Callable[[SpotAnalysisOperable], bool] = False, base_image_selector: str | ImageType | None = None)

Bases: AbstractVisualizationImageProcessor

Interprets the current image as a 2D cross section and either displays it, or if interactive it displays the plot and waits on the next press of the “enter” key.

This visualization uses either one or two windows to display the cross sections, depending on the initialization parameters.

Custom rendering code can be added by extending this class and overriding the pre_visualize() and post_visualize() functions.

Parameters:

cross_section_location (Callable[[SpotAnalysisOperable], tuple[int, int]] | tuple[int, int] | str | PixelOfInterest) – The (x, y) pixel location to take cross sections through.
single_plot (bool, optional) – If True, then draw both the horizational and vertical cross section graphs on the same plot. If False, then use two separate plots. Default is True.
crop_to_threshold (int | None, optional) – Crops the input image horizontally and vertically to the first/last values >= the given threshold. This crop is based on the cross_section_location and is done before the cross section is measured. This is useful when trying to inspect hot spots where the interesting values are limited to a small portion of the image. None to not crop the image. By default None.
y_range (tuple[int, int] | None, optional) – Set the y-range of the cross-section plots. None to not constrain the y-axis range with this parameter. Default is None.
plot_title (str | Callable[[SpotAnalysisOperable], str] | Literal[False], optional) – The title to use for the plots, or the boolean value False to supress the title. Default is the image name.

close_figures(): Closes all visualization windows created by this instance.

init_figure_records(render_control_figure: RenderControlFigure) → list[RenderControlFigureRecord]

Initializes the figure windows (via figure_management.setup_figure*) for this instance and returns the list of initialized figures. The length of this list ideally should match what was previously returned for num_figures.

Parameters:: render_control_fig (rcf.RenderControlFigure) – The render controller to use during figure setup.
Returns:: figures – The list of newly created figure windows.
Return type:: list[rcfr.RenderControlFigureRecord]

property num_figures: int: How many figure windows this instance intends to create. Must be available at all times after this instance has been initialized.

visualize_operable(operable: SpotAnalysisOperable, is_last: bool, base_image: CacheableImage) → list[CacheableImage | RenderControlFigureRecord]

Updates the figures for this instance with the data from the given operable.

The implementing visualization image processor has the option of returning visualizations as cacheable images, figure records, or a mix of both.

Parameters:

operable (SpotAnalysisOperable) – The operable to draw the visualization for.
is_last (bool) – True if this is the last operable to be drawn by this processor.
base_image (CacheableImage) – The base image on which to draw the visualization. Value is determined by base_image_selector and retrieved with _get_image_for_visualizing().

Returns:

visualizations – Visualizations from this image processor as cacheable images or as figure records. Figure records preferred. Empty list if there aren’t any.

Return type:

list[CacheableImage|rcfr.RenderControlFigureRecord]