Extraction API

Shape definitions, measurement extractors, merge utilities, and the Dash-based extraction GUI implementation, including interactive extraction callbacks.

Field Specification

Field metadata shared by extraction and dashboard workflows.

GONet Wizard stores field definitions in data_spec.yaml so that serialized extraction outputs, dashboard labels, plotting units, and legacy aliases remain consistent across the package. This module loads that YAML file at import time and exposes the result as DATA_SPEC, a mapping from canonical field keys to Field objects.

The field specification is intentionally lightweight. It does not perform data loading by itself; instead, loaders and extractors use it to discover how values should be named, displayed, grouped, and matched against older output formats.

GONet_Wizard.GONet_utils.src.data_spec.DATA_SPEC_PATH

Path to the package-shipped data_spec.yaml file.

Type:: pathlib.Path

GONet_Wizard.GONet_utils.src.data_spec.DATA_SPEC

Mapping from canonical field keys to Field metadata objects.

Type:: dict

GONet_Wizard.GONet_utils.src.data_spec.Classes

-------

:class:`Field`: Metadata container describing one extraction/dashboard field.

class GONet_Wizard.GONet_utils.src.data_spec.Field(key, label, unit, aliases=None, plottable=True, field_type='env', **extras)[source]

Bases: object

Represents a single named field to extract.

Parameters:

key (str) – Canonical key for the field.
label (str) – Human-readable label for display or plotting.
unit (str) – String representation of the unit (for display only).
aliases (list of str) – List of legacy or alternate field names.
plottable (bool) – Whether this field should be available for plotting.
field_type (str) – Type of field, either ‘env’ (environment) or ‘chn’ (channel).
extras (dict) – Additional metadata for loading or processing the field.

Extraction Shapes

This subpackage defines a set of geometric shape classes used to describe regions of interest in 2D images. These shapes support common operations such as:

Construction from different parameterizations
Validation of geometric properties
Drawing and visualization
Masking of NumPy arrays using the shape footprint

Each shape class inherits from a shared abstract base class that ensures a unified interface for working with different geometries in the GONet ecosystem.

Submodules

base :
Defines the abstract base class Shape and shared functionality for all shape types. Also defines the IncompleteShapeError
circle :
Implements a circular region defined by a center point and radius.
annulus :
Defines an annular (ring-shaped) region described by an inner and outer radius.
path :
Represents a general closed path using SVG-style path strings. Used for rectangles too.

class GONet_Wizard.GONet_utils.src.extract_app.shapes.Shape(**params)[source]

Bases: ABC

Abstract base class for geometric shapes used in extraction operations.

The Shape class provides a framework for defining and working with geometric shapes such as circles, rectangles, and paths. Subclasses must implement methods for validation, drawing, masking, and extracting fields.

_registry

A class-level dictionary that maps shape type strings (e.g., “circle”, “annulus”, “rectangle”) to their corresponding shape subclasses. Rectangles are handled by the path subclass. This registry allows dynamic instantiation of shape objects based on their type.

Type:: dict

Notes

Subclasses must use the Shape.register() decorator to register themselves with the registry.

abstract get_extractor_field()[source]

Provide the keys and parameters required for pixel count extraction.

This method is implemented by subclasses of Shape to return a dictionary containing the parameters necessary for ExtractionValues to perform pixel count extraction. The keys in the returned dictionary must match the expected structure defined in GONet_Wizard.GONet_utils.DATA_SPEC.

Return type:: dict
Returns:: dict – A dictionary containing the shape-specific parameters required for extraction. The keys correspond to the fields expected by ExtractionValues.

Notes

Subclasses of Shape must implement this method to provide the correct parameters for their specific geometry (e.g., circle, annulus, path).
Rectangular regions are represented by the path subclass.
ExtractionValues uses these parameters to generate masks and compute statistics for pixel values within the defined shape.

abstract validate()[source]

Validate the parameters of the shape.

This method should be implemented by subclasses to ensure that all required parameters are properly defined and meet the shape-specific constraints.

Raises:

IncompleteShapeError – If any required parameter is missing or undefined.
TypeError – If any parameter is not of the expected type.
ValueError – If any parameter fails validation (e.g., negative values).

Return type:

None

abstract draw(n_segments=60)[source]

Draw the shape.

This method should be implemented by subclasses to return a list of dictionaries representing the shapes. Each dictionary corresponds to a closed shape.

Parameters:: n_segments (int, optional) – Number of line segments to use for approximating curved shapes (e.g., arcs). Defaults to 60.
Return type:: list[dict]
Returns:: list`[:class:`dict] – A list of dictionaries representing the shapes’ geometry.

Notes

This method is used for visualization or integration with external tools (e.g., Plotly).

abstract plt_draw(ax, **kwargs)[source]

Draw the shape on a Matplotlib Axes.

This method should be implemented by subclasses to render the shape on the provided Matplotlib Axes object.

Parameters:

ax (matplotlib.axes.Axes) – The Matplotlib Axes object on which to draw the shape.
**kwargs (dict) – Additional keyword arguments to customize the appearance of the shape.

Return type:

None

Returns:

None

Notes

This method is used for visualization within Matplotlib plots.

abstract mask(image)[source]

Create a boolean mask for pixels inside the shape.

This method should be implemented by subclasses to return a NumPy array representing a mask where pixels inside the shape are marked as True and pixels outside the shape are marked as False.

Parameters:: image (numpy.ndarray or list) – The input image or array to apply the mask to, typically the channel of a GONet image.
Return type:: ndarray
Returns:: numpy.ndarray – A boolean array where True indicates pixels inside the shape.

classmethod register(*shape_types)[source]

Register a shape subclass with one or more type aliases.

This method is used to associate a shape subclass with specific type strings (e.g., “circle”, “rectangle”) in the _registry dictionary. The _registry allows dynamic instantiation of shape objects based on their type strings.

Parameters:: shape_types (str) – One or more type aliases for the shape subclass. These aliases are used to identify the shape type when creating instances dynamically.
Returns:: function – A decorator function that registers the subclass with the provided aliases.

Notes

Subclasses must use this decorator to register themselves with the _registry.
The CLASS_ALIASES attribute is added to the subclass, containing the registered shape type aliases.

classmethod from_dict(data)[source]

Create a shape instance from a dictionary of parameters.

This method dynamically instantiates a shape object based on the shape key in the provided dictionary. The shape key must correspond to one of the registered shape types in the _registry.

Parameters:: data (dict) – A dictionary containing the parameters for the shape. The dictionary must include a shape key specifying the type of shape (e.g., “circle”, “rectangle”). Additional keys in the dictionary are passed to the shape subclass for initialization.
Return type:: Shape
Returns:: Shape – An instance of the appropriate shape subclass, initialized with the parameters from the dictionary.
Raises:: ValueError – If the shape key is missing or if the specified shape type is not registered.

Notes

Subclasses must implement their own from_dict method to handle initialization from the dictionary.

class GONet_Wizard.GONet_utils.src.extract_app.shapes.Circle(x0, y0, radius, start_angle=-180, end_angle=180)[source]

Bases: Shape

Represents a circular sector shape for pixel extraction.

The Circle class is derived from the Shape class and provides functionality to define, validate, and manipulate circular sector shapes. It supports operations such as generating masks for pixel selection, creating Plotly-compatible shapes for visualization, and extracting parameters from dictionaries.

The register() decorator adds circle to the shape registry.

validate()[source]

Validate and convert the circle parameters.

This method ensures that all parameters are numeric and converts string representations of numbers to floats.

Raises:

.base.IncompleteShapeError – If any required parameter is missing.
TypeError – If any parameter is not a numeric type or a string representing a number.
ValueError – If radius is not positive or angles are out of range.

Return type:

None

get_extractor_field()[source]

Retrieve the extraction parameters as a dictionary.

This method returns a dictionary containing the geometric parameters of the circular sector, mapped to their corresponding keys as defined in the DATA_SPEC.

Return type:: dict
Returns:: dict – A dictionary with the following keys and their corresponding values: - shape: The name of the shape, set to “circle”. - x0: X-coordinate of the center of the circle. - y0: Y-coordinate of the center of the circle. - radius: Radius of the circle. - start_angle: Start angle of the circular sector in degrees. - end_angle: End angle of the circular sector in degrees.

Notes

This method is used to standardize the extraction parameters for use in the extraction pipeline.

draw(n_segments=60)[source]

Generate Plotly-compatible shape(s) for a circular sector or full circle.

This method creates a visual representation of the circular sector or full circle as Plotly-compatible shapes. The circular sector is approximated using a specified number of line segments for the arc.

Parameters:: n_segments (int, optional) – Number of line segments to approximate the arc (default: 60).
Return type:: list[dict]
Returns:: list of dict – A list of Plotly shape dictionaries representing the circular sector or full circle.

plt_draw(ax, **kwargs)[source]

Draw the circular sector on a Matplotlib Axes.

This method adds a visual representation of the circular sector or full circle to the provided Matplotlib Axes object.

Parameters:

ax (matplotlib.axes.Axes) – The Matplotlib Axes object to draw the shape on.
**kwargs (dict) – Additional keyword arguments to customize the appearance of the shape.

Return type:

None

Returns:

None

mask(data)[source]

Create a boolean mask selecting pixels inside a circular sector.

This method generates a 2D boolean mask where pixels inside the circular sector are marked as True and others as False. The circular sector is defined by its center, radius, and angular range.

Parameters:: data (numpy.ndarray or list) – 2D array or nested list representing the image data.
Return type:: ndarray
Returns:: numpy.ndarray – A boolean mask with the same shape as data, where True indicates pixels inside the circular sector.

classmethod from_dict(data)[source]

Create a Circle object from a dictionary of parameters.

This method instantiates a Circle object using a dictionary containing the required geometric parameters.

Parameters:: data (dict) – A dictionary containing the following keys: - x0 (float): X-coordinate of the center of the circle. - y0 (float): Y-coordinate of the center of the circle. - param1 (float): Radius of the circle. - start_angle (float): Start angle of the circular sector in degrees. - end_angle (float): End angle of the circular sector in degrees.
Returns:: Circle – An instance of the Circle class initialized with the provided parameters.

class GONet_Wizard.GONet_utils.src.extract_app.shapes.Annulus(x0, y0, inner_radius, outer_radius, start_angle=-180, end_angle=180)[source]

Bases: Shape

Represents an annular sector shape for pixel extraction.

The Annulus class is derived from the Shape class and provides functionality to define, validate, and manipulate annular sector shapes. It supports operations such as generating masks for pixel selection, creating Plotly-compatible shapes for visualization, and extracting parameters from dictionaries.

The register() decorator adds annulus to the shape registry.

validate()[source]

Validate and convert the annular sector parameters.

This method ensures that all parameters are numeric and converts string representations of numbers to floats.

Raises:

.base.IncompleteShapeError – If any required parameter is missing.
TypeError – If any parameter is not a numeric type or a string representing a number.
ValueError – If radii are not positive or if outer_radius is not greater than inner_radius.

Return type:

None

get_extractor_field()[source]

Retrieve the extraction parameters as a dictionary.

This method returns a dictionary containing the geometric parameters of the annular sector, mapped to their corresponding keys as defined in the DATA_SPEC.

Return type:

dict

Returns:

dict – A dictionary with the following keys and their corresponding values:

shape: Name of the shape, set to “annulus”.
x0: X-coordinate of the center of the annulus.
y0: Y-coordinate of the center of the annulus.
inner_radius: Inner radius of the annulus.
outer_radius: Outer radius of the annulus.
start_angle: Start angle of the annular sector in degrees.
end_angle: End angle of the annular sector in degrees.

Notes

This method is used to standardize the extraction parameters for use in the extraction pipeline.

draw(n_segments=60)[source]

Generate Plotly-compatible shape(s) for an annular sector using straight line segments.

This method creates a visual representation of the annular sector or full annulus as Plotly-compatible shapes. The annular sector is approximated using a specified number of line segments for the arcs.

Parameters:: n_segments (int, optional) – Number of line segments to approximate each arc (default: 60).
Return type:: list[dict]
Returns:: list of dict – A list of Plotly shape dictionaries representing the annular sector or full annulus.
Raises:: ValueError – If the radii are not positive or if inner_radius is greater than or equal to outer_radius.

plt_draw(ax, **kwargs)[source]

Draw the annular sector on a Matplotlib Axes.

This method adds a visual representation of the annular sector or full annulus to the provided Matplotlib Axes object.

Parameters:

ax (matplotlib.axes.Axes) – The Matplotlib Axes object to draw the shape on.
**kwargs (dict) – Additional keyword arguments to customize the appearance of the shape.

Return type:

None

Returns:

None

mask(data)[source]

Create a boolean mask selecting pixels inside the annular sector.

This method generates a 2D boolean mask for an annular sector, where pixels inside the defined region are marked as True and others as False. The annular sector is defined by its center, inner and outer radii, and angular range.

Parameters:: data (numpy.ndarray or list) – 2D array or nested list representing the image data.
Return type:: ndarray
Returns:: numpy.ndarray – A boolean mask with the same shape as data, where True indicates pixels inside the annular sector.

classmethod from_dict(data)[source]

Create an Annulus object from a dictionary of parameters.

This method instantiates an Annulus object using a dictionary containing the required geometric parameters.

Parameters:: data (dict) – A dictionary containing the following keys: - x0 (float): X-coordinate of the center of the annulus. - y0 (float): Y-coordinate of the center of the annulus. - param1 (float): Inner radius of the annulus. - param2 (float): Outer radius of the annulus. - start_angle (float): Start angle of the annular sector in degrees. - end_angle (float): End angle of the annular sector in degrees.
Returns:: Annulus – An instance of the Annulus class initialized with the provided parameters.

class GONet_Wizard.GONet_utils.src.extract_app.shapes.Path(shape_name, path_str)[source]

Bases: Shape

Represents a generic path shape for pixel extraction.

The Path class is derived from the Shape class and provides functionality to define, validate, and manipulate path shapes. It supports operations such as generating masks for pixel selection, creating Plotly-compatible shapes for visualization, and extracting parameters from dictionaries.

The register() decorator adds path, freehand, and rectangle to the shape registry.

A rectangle shape will be Path shape, instantiated using the from_rectangle() class method.

validate()[source]

Validate the SVG path string.

Raises:

.base.IncompleteShapeError – If the path string is None.
TypeError – If the path string is not a string.
ValueError – If the path string is malformed or does not match the SVG path format.

Return type:

None

get_extractor_field()[source]

Retrieve the extraction parameters as a dictionary.

This method returns a dictionary containing the SVG path string, mapped to its corresponding key as defined in the DATA_SPEC.

Return type:: dict
Returns:: dict – A dictionary with the following structure: - shape (str): The shape name (e.g., “path”, “rectangle”). - path (str): The SVG path string defining the shape (if applicable). - For rectangles, additional keys such as x0, y0, side1, side2, start_angle, and end_angle.

Notes

This method is used to standardize the extraction parameters for use in the extraction pipeline.

classmethod from_rectangle(x0, y0, side1, side2, start_angle=-180, end_angle=180)[source]

Generate an SVG path for a rectangular sector.

A few hidden attributes are added to the returned object for completeness:

_x0, _y0: Center coordinates.
_side1, _side2: Side lengths.
_start_angle, _end_angle: Start and end angles in degrees.

Parameters:

x0 (float) – X-coordinate of the center.
y0 (float) – Y-coordinate of the center.
side1 (float) – Side 1 length.
side2 (float) – Side 2 length.
start_angle (float) – Start angle in degrees.
end_angle (float) – End angle in degrees.

Return type:

Path

Returns:

Path – A Path object initialized with the SVG path string for the rectangular sector.

Raises:

TypeError – If any parameter is not a numeric type or a string representing a number.
ValueError – If side lengths are not positive or angles are invalid.

draw()[source]

Generate a Plotly-compatible shape for the path.

This method creates a visual representation of the path as a Plotly-compatible shape. The path is defined using the SVG path string stored in the object.

Return type:

list[dict]

Returns:

list of dict – A list containing a single Plotly shape dictionary with the following properties:

type: Set to “path”.
path: The SVG path string defining the shape.

plt_draw(ax, **kwargs)[source]

Draw the path on a Matplotlib Axes.

This method renders the path defined by the SVG path string onto the provided Matplotlib Axes object.

Parameters:

ax (matplotlib.axes.Axes) – The Matplotlib Axes object to draw the shape on.
**kwargs (dict) – Additional keyword arguments to customize the appearance of the shape.

Return type:

None

Returns:

None

mask(data)[source]

Create a boolean mask selecting pixels inside a closed SVG path.

This method generates a 2D boolean mask where pixels inside the closed path defined by the SVG path string are marked as True, and others as False.

Parameters:: data (numpy.ndarray or list) – 2D array or nested list representing the image data.
Return type:: ndarray
Returns:: numpy.ndarray – A boolean mask with the same shape as data, where True indicates pixels inside the closed path.

classmethod from_dict(data)[source]

Create a Path object from a dictionary of parameters.

This method dynamically creates a Path object based on the shape key in the provided dictionary. If the shape is “rectangle”, the from_rectangle method is used to generate the path. Otherwise, the path key is used to initialize the object with an SVG path string.

Parameters:

data (dict) –

A dictionary containing the following keys:

shape (str): The type of shape (e.g., “path”, “freehand”, “rectangle”).
path (str, optional): The SVG path string defining the shape (required for “path” or “freehand”).
x0 (float, optional): X-coordinate of the center (required for “rectangle”).
y0 (float, optional): Y-coordinate of the center (required for “rectangle”).
param1 (float, optional): Side 1 length (required for “rectangle”).
param2 (float, optional): Side 2 length (required for “rectangle”).
start_angle (float, optional): Start angle in degrees (required for “rectangle”).
end_angle (float, optional): End angle in degrees (required for “rectangle”).

Returns:

Path – A Path object initialized with the provided parameters.

Raises:

KeyError – If required keys are missing from the dictionary.
ValueError – If the shape key is not recognized or the parameters are invalid.

exception GONet_Wizard.GONet_utils.src.extract_app.shapes.IncompleteShapeError[source]

Bases: Exception

Exception raised when a required shape parameter is not defined.

This error is used to indicate that a shape parameter, which is expected to be provided for the proper functioning of a shape-related operation, is missing or set to None.

Shape framework for interactive and scripted extraction regions

This module defines the abstract Shape API used by both the extraction GUI and the command-line extraction pipeline. Shape subclasses validate their own geometry, draw Plotly/Matplotlib representations, and create boolean masks that select pixels from an image channel.

Shape objects can be constructed directly by their subclasses or indirectly via Shape.from_dict(), which reads the "shape" key from an extraction parameter dictionary. This is the path used by the extraction command and the interactive GUI when they pass user-selected regions to the extractor pipeline.

Classes

IncompleteShapeError: Raised when a required shape parameter is missing.
Shape: Abstract base class and registry for all extraction-region shapes.

Functions

normalize_angle_deg(): Normalize angles to the [-180, 180] degree range.
build_arc_path(): Approximate a circular arc as an SVG path string.

exception GONet_Wizard.GONet_utils.src.extract_app.shapes.base.IncompleteShapeError[source]

Bases: Exception

Exception raised when a required shape parameter is not defined.

This error is used to indicate that a shape parameter, which is expected to be provided for the proper functioning of a shape-related operation, is missing or set to None.

class GONet_Wizard.GONet_utils.src.extract_app.shapes.base.Shape(**params)[source]

Bases: ABC

Abstract base class for geometric shapes used in extraction operations.

The Shape class provides a framework for defining and working with geometric shapes such as circles, rectangles, and paths. Subclasses must implement methods for validation, drawing, masking, and extracting fields.

_registry

A class-level dictionary that maps shape type strings (e.g., “circle”, “annulus”, “rectangle”) to their corresponding shape subclasses. Rectangles are handled by the path subclass. This registry allows dynamic instantiation of shape objects based on their type.

Type:: dict

Notes

Subclasses must use the Shape.register() decorator to register themselves with the registry.

abstract get_extractor_field()[source]

Provide the keys and parameters required for pixel count extraction.

This method is implemented by subclasses of Shape to return a dictionary containing the parameters necessary for ExtractionValues to perform pixel count extraction. The keys in the returned dictionary must match the expected structure defined in GONet_Wizard.GONet_utils.DATA_SPEC.

Return type:: dict
Returns:: dict – A dictionary containing the shape-specific parameters required for extraction. The keys correspond to the fields expected by ExtractionValues.

Notes

Subclasses of Shape must implement this method to provide the correct parameters for their specific geometry (e.g., circle, annulus, path).
Rectangular regions are represented by the path subclass.
ExtractionValues uses these parameters to generate masks and compute statistics for pixel values within the defined shape.

abstract validate()[source]

Validate the parameters of the shape.

This method should be implemented by subclasses to ensure that all required parameters are properly defined and meet the shape-specific constraints.

Raises:

IncompleteShapeError – If any required parameter is missing or undefined.
TypeError – If any parameter is not of the expected type.
ValueError – If any parameter fails validation (e.g., negative values).

Return type:

None

abstract draw(n_segments=60)[source]

Draw the shape.

This method should be implemented by subclasses to return a list of dictionaries representing the shapes. Each dictionary corresponds to a closed shape.

Parameters:: n_segments (int, optional) – Number of line segments to use for approximating curved shapes (e.g., arcs). Defaults to 60.
Return type:: list[dict]
Returns:: list`[:class:`dict] – A list of dictionaries representing the shapes’ geometry.

Notes

This method is used for visualization or integration with external tools (e.g., Plotly).

abstract plt_draw(ax, **kwargs)[source]

Draw the shape on a Matplotlib Axes.

This method should be implemented by subclasses to render the shape on the provided Matplotlib Axes object.

Parameters:

ax (matplotlib.axes.Axes) – The Matplotlib Axes object on which to draw the shape.
**kwargs (dict) – Additional keyword arguments to customize the appearance of the shape.

Return type:

None

Returns:

None

Notes

This method is used for visualization within Matplotlib plots.

abstract mask(image)[source]

Create a boolean mask for pixels inside the shape.

This method should be implemented by subclasses to return a NumPy array representing a mask where pixels inside the shape are marked as True and pixels outside the shape are marked as False.

Parameters:: image (numpy.ndarray or list) – The input image or array to apply the mask to, typically the channel of a GONet image.
Return type:: ndarray
Returns:: numpy.ndarray – A boolean array where True indicates pixels inside the shape.

classmethod register(*shape_types)[source]

Register a shape subclass with one or more type aliases.

This method is used to associate a shape subclass with specific type strings (e.g., “circle”, “rectangle”) in the _registry dictionary. The _registry allows dynamic instantiation of shape objects based on their type strings.

Parameters:: shape_types (str) – One or more type aliases for the shape subclass. These aliases are used to identify the shape type when creating instances dynamically.
Returns:: function – A decorator function that registers the subclass with the provided aliases.

Notes

Subclasses must use this decorator to register themselves with the _registry.
The CLASS_ALIASES attribute is added to the subclass, containing the registered shape type aliases.

classmethod from_dict(data)[source]

Create a shape instance from a dictionary of parameters.

This method dynamically instantiates a shape object based on the shape key in the provided dictionary. The shape key must correspond to one of the registered shape types in the _registry.

Parameters:: data (dict) – A dictionary containing the parameters for the shape. The dictionary must include a shape key specifying the type of shape (e.g., “circle”, “rectangle”). Additional keys in the dictionary are passed to the shape subclass for initialization.
Return type:: Shape
Returns:: Shape – An instance of the appropriate shape subclass, initialized with the parameters from the dictionary.
Raises:: ValueError – If the shape key is missing or if the specified shape type is not registered.

Notes

Subclasses must implement their own from_dict method to handle initialization from the dictionary.

GONet_Wizard.GONet_utils.src.extract_app.shapes.base.normalize_angle_deg(angle)[source]

Normalize an angle in degrees to the range [-180, 180], inclusive.

Parameters:: angle (float) – Input angle in degrees.
Return type:: float
Returns:: float – Normalized angle in the range [-180, 180].

GONet_Wizard.GONet_utils.src.extract_app.shapes.base.build_arc_path(x0, y0, r, start_angle, end_angle, n_segments=60)[source]

Generate the SVG path string for a circular arc using straight line segments.

Parameters:

x0 (float) – X-coordinate of the circle center.
y0 (float) – Y-coordinate of the circle center.
r (float) – Radius of the arc.
start_angle (float) – Starting angle in degrees.
end_angle (float) – Ending angle in degrees.
n_segments (int) – Number of line segments to use for arc approximation.

Return type:

str

Returns:

str – SVG path fragment using only ‘L’ commands, starting from the first point on the arc.

This module defines the Circle class, which represents a circular sector shape for pixel extraction. The Circle class is derived from the Shape class and provides functionality for defining, validating, and manipulating circular sector shapes.

The Circle class is registered in the Shape framework via the register() decorator, allowing dynamic instantiation based on the shape key in extraction parameters.

Classes

Circle: Represents a circular sector shape for pixel extraction, supporting operations such as mask generation, visualization, and parameter extraction.

class GONet_Wizard.GONet_utils.src.extract_app.shapes.circle.Circle(x0, y0, radius, start_angle=-180, end_angle=180)[source]

Bases: Shape

Represents a circular sector shape for pixel extraction.

The Circle class is derived from the Shape class and provides functionality to define, validate, and manipulate circular sector shapes. It supports operations such as generating masks for pixel selection, creating Plotly-compatible shapes for visualization, and extracting parameters from dictionaries.

The register() decorator adds circle to the shape registry.

validate()[source]

Validate and convert the circle parameters.

This method ensures that all parameters are numeric and converts string representations of numbers to floats.

Raises:

.base.IncompleteShapeError – If any required parameter is missing.
TypeError – If any parameter is not a numeric type or a string representing a number.
ValueError – If radius is not positive or angles are out of range.

Return type:

None

get_extractor_field()[source]

Retrieve the extraction parameters as a dictionary.

This method returns a dictionary containing the geometric parameters of the circular sector, mapped to their corresponding keys as defined in the DATA_SPEC.

Return type:: dict
Returns:: dict – A dictionary with the following keys and their corresponding values: - shape: The name of the shape, set to “circle”. - x0: X-coordinate of the center of the circle. - y0: Y-coordinate of the center of the circle. - radius: Radius of the circle. - start_angle: Start angle of the circular sector in degrees. - end_angle: End angle of the circular sector in degrees.

Notes

This method is used to standardize the extraction parameters for use in the extraction pipeline.

draw(n_segments=60)[source]

Generate Plotly-compatible shape(s) for a circular sector or full circle.

This method creates a visual representation of the circular sector or full circle as Plotly-compatible shapes. The circular sector is approximated using a specified number of line segments for the arc.

Parameters:: n_segments (int, optional) – Number of line segments to approximate the arc (default: 60).
Return type:: list[dict]
Returns:: list of dict – A list of Plotly shape dictionaries representing the circular sector or full circle.

plt_draw(ax, **kwargs)[source]

Draw the circular sector on a Matplotlib Axes.

This method adds a visual representation of the circular sector or full circle to the provided Matplotlib Axes object.

Parameters:

ax (matplotlib.axes.Axes) – The Matplotlib Axes object to draw the shape on.
**kwargs (dict) – Additional keyword arguments to customize the appearance of the shape.

Return type:

None

Returns:

None

mask(data)[source]

Create a boolean mask selecting pixels inside a circular sector.

This method generates a 2D boolean mask where pixels inside the circular sector are marked as True and others as False. The circular sector is defined by its center, radius, and angular range.

Parameters:: data (numpy.ndarray or list) – 2D array or nested list representing the image data.
Return type:: ndarray
Returns:: numpy.ndarray – A boolean mask with the same shape as data, where True indicates pixels inside the circular sector.

classmethod from_dict(data)[source]

Create a Circle object from a dictionary of parameters.

This method instantiates a Circle object using a dictionary containing the required geometric parameters.

Parameters:: data (dict) – A dictionary containing the following keys: - x0 (float): X-coordinate of the center of the circle. - y0 (float): Y-coordinate of the center of the circle. - param1 (float): Radius of the circle. - start_angle (float): Start angle of the circular sector in degrees. - end_angle (float): End angle of the circular sector in degrees.
Returns:: Circle – An instance of the Circle class initialized with the provided parameters.

This module defines the Annulus class, which represents an annular sector shape for pixel extraction. The Annulus class is derived from the Shape class and provides functionality for defining, validating, and manipulating annular sector shapes.

The Annulus class is registered in the Shape framework via the @Shape.register(“annulus”) decorator, allowing dynamic instantiation based on the shape key in extraction parameters.

Classes

Annulus: Represents an annular sector shape for pixel extraction, supporting operations such as mask generation, visualization, and parameter extraction.

class GONet_Wizard.GONet_utils.src.extract_app.shapes.annulus.Annulus(x0, y0, inner_radius, outer_radius, start_angle=-180, end_angle=180)[source]

Bases: Shape

Represents an annular sector shape for pixel extraction.

The Annulus class is derived from the Shape class and provides functionality to define, validate, and manipulate annular sector shapes. It supports operations such as generating masks for pixel selection, creating Plotly-compatible shapes for visualization, and extracting parameters from dictionaries.

The register() decorator adds annulus to the shape registry.

validate()[source]

Validate and convert the annular sector parameters.

This method ensures that all parameters are numeric and converts string representations of numbers to floats.

Raises:

.base.IncompleteShapeError – If any required parameter is missing.
TypeError – If any parameter is not a numeric type or a string representing a number.
ValueError – If radii are not positive or if outer_radius is not greater than inner_radius.

Return type:

None

get_extractor_field()[source]

Retrieve the extraction parameters as a dictionary.

This method returns a dictionary containing the geometric parameters of the annular sector, mapped to their corresponding keys as defined in the DATA_SPEC.

Return type:

dict

Returns:

dict – A dictionary with the following keys and their corresponding values:

shape: Name of the shape, set to “annulus”.
x0: X-coordinate of the center of the annulus.
y0: Y-coordinate of the center of the annulus.
inner_radius: Inner radius of the annulus.
outer_radius: Outer radius of the annulus.
start_angle: Start angle of the annular sector in degrees.
end_angle: End angle of the annular sector in degrees.

Notes

This method is used to standardize the extraction parameters for use in the extraction pipeline.

draw(n_segments=60)[source]

Generate Plotly-compatible shape(s) for an annular sector using straight line segments.

This method creates a visual representation of the annular sector or full annulus as Plotly-compatible shapes. The annular sector is approximated using a specified number of line segments for the arcs.

Parameters:: n_segments (int, optional) – Number of line segments to approximate each arc (default: 60).
Return type:: list[dict]
Returns:: list of dict – A list of Plotly shape dictionaries representing the annular sector or full annulus.
Raises:: ValueError – If the radii are not positive or if inner_radius is greater than or equal to outer_radius.

plt_draw(ax, **kwargs)[source]

Draw the annular sector on a Matplotlib Axes.

This method adds a visual representation of the annular sector or full annulus to the provided Matplotlib Axes object.

Parameters:

ax (matplotlib.axes.Axes) – The Matplotlib Axes object to draw the shape on.
**kwargs (dict) – Additional keyword arguments to customize the appearance of the shape.

Return type:

None

Returns:

None

mask(data)[source]

Create a boolean mask selecting pixels inside the annular sector.

This method generates a 2D boolean mask for an annular sector, where pixels inside the defined region are marked as True and others as False. The annular sector is defined by its center, inner and outer radii, and angular range.

Parameters:: data (numpy.ndarray or list) – 2D array or nested list representing the image data.
Return type:: ndarray
Returns:: numpy.ndarray – A boolean mask with the same shape as data, where True indicates pixels inside the annular sector.

classmethod from_dict(data)[source]

Create an Annulus object from a dictionary of parameters.

This method instantiates an Annulus object using a dictionary containing the required geometric parameters.

Parameters:: data (dict) – A dictionary containing the following keys: - x0 (float): X-coordinate of the center of the annulus. - y0 (float): Y-coordinate of the center of the annulus. - param1 (float): Inner radius of the annulus. - param2 (float): Outer radius of the annulus. - start_angle (float): Start angle of the annular sector in degrees. - end_angle (float): End angle of the annular sector in degrees.
Returns:: Annulus – An instance of the Annulus class initialized with the provided parameters.

This module defines the Path class, which represents a generic path shape for pixel extraction. The Path class is derived from the Shape class and provides functionality for defining, validating, and manipulating path-based shapes. It supports operations such as generating masks for pixel selection, creating Plotly-compatible shapes for visualization, and extracting parameters from dictionaries.

The Path class is registered in the Shape framework via the register() decorator, with the aliases path, freehand, and rectangle. This allows dynamic instantiation of Path objects based on the shape key in extraction parameters.

Classes

Path: Represents a generic path shape for pixel extraction, supporting operations such as mask generation, visualization, and parameter extraction.

class GONet_Wizard.GONet_utils.src.extract_app.shapes.path.Path(shape_name, path_str)[source]

Bases: Shape

Represents a generic path shape for pixel extraction.

The Path class is derived from the Shape class and provides functionality to define, validate, and manipulate path shapes. It supports operations such as generating masks for pixel selection, creating Plotly-compatible shapes for visualization, and extracting parameters from dictionaries.

The register() decorator adds path, freehand, and rectangle to the shape registry.

A rectangle shape will be Path shape, instantiated using the from_rectangle() class method.

validate()[source]

Validate the SVG path string.

Raises:

.base.IncompleteShapeError – If the path string is None.
TypeError – If the path string is not a string.
ValueError – If the path string is malformed or does not match the SVG path format.

Return type:

None

get_extractor_field()[source]

Retrieve the extraction parameters as a dictionary.

This method returns a dictionary containing the SVG path string, mapped to its corresponding key as defined in the DATA_SPEC.

Return type:: dict
Returns:: dict – A dictionary with the following structure: - shape (str): The shape name (e.g., “path”, “rectangle”). - path (str): The SVG path string defining the shape (if applicable). - For rectangles, additional keys such as x0, y0, side1, side2, start_angle, and end_angle.

Notes

This method is used to standardize the extraction parameters for use in the extraction pipeline.

classmethod from_rectangle(x0, y0, side1, side2, start_angle=-180, end_angle=180)[source]

Generate an SVG path for a rectangular sector.

A few hidden attributes are added to the returned object for completeness:

_x0, _y0: Center coordinates.
_side1, _side2: Side lengths.
_start_angle, _end_angle: Start and end angles in degrees.

Parameters:

x0 (float) – X-coordinate of the center.
y0 (float) – Y-coordinate of the center.
side1 (float) – Side 1 length.
side2 (float) – Side 2 length.
start_angle (float) – Start angle in degrees.
end_angle (float) – End angle in degrees.

Return type:

Path

Returns:

Path – A Path object initialized with the SVG path string for the rectangular sector.

Raises:

TypeError – If any parameter is not a numeric type or a string representing a number.
ValueError – If side lengths are not positive or angles are invalid.

draw()[source]

Generate a Plotly-compatible shape for the path.

This method creates a visual representation of the path as a Plotly-compatible shape. The path is defined using the SVG path string stored in the object.

Return type:

list[dict]

Returns:

list of dict – A list containing a single Plotly shape dictionary with the following properties:

type: Set to “path”.
path: The SVG path string defining the shape.

plt_draw(ax, **kwargs)[source]

Draw the path on a Matplotlib Axes.

This method renders the path defined by the SVG path string onto the provided Matplotlib Axes object.

Parameters:

ax (matplotlib.axes.Axes) – The Matplotlib Axes object to draw the shape on.
**kwargs (dict) – Additional keyword arguments to customize the appearance of the shape.

Return type:

None

Returns:

None

mask(data)[source]

Create a boolean mask selecting pixels inside a closed SVG path.

This method generates a 2D boolean mask where pixels inside the closed path defined by the SVG path string are marked as True, and others as False.

Parameters:: data (numpy.ndarray or list) – 2D array or nested list representing the image data.
Return type:: ndarray
Returns:: numpy.ndarray – A boolean mask with the same shape as data, where True indicates pixels inside the closed path.

classmethod from_dict(data)[source]

Create a Path object from a dictionary of parameters.

This method dynamically creates a Path object based on the shape key in the provided dictionary. If the shape is “rectangle”, the from_rectangle method is used to generate the path. Otherwise, the path key is used to initialize the object with an SVG path string.

Parameters:

data (dict) –

A dictionary containing the following keys:

shape (str): The type of shape (e.g., “path”, “freehand”, “rectangle”).
path (str, optional): The SVG path string defining the shape (required for “path” or “freehand”).
x0 (float, optional): X-coordinate of the center (required for “rectangle”).
y0 (float, optional): Y-coordinate of the center (required for “rectangle”).
param1 (float, optional): Side 1 length (required for “rectangle”).
param2 (float, optional): Side 2 length (required for “rectangle”).
start_angle (float, optional): Start angle in degrees (required for “rectangle”).
end_angle (float, optional): End angle in degrees (required for “rectangle”).

Returns:

Path – A Path object initialized with the provided parameters.

Raises:

KeyError – If required keys are missing from the dictionary.
ValueError – If the shape key is not recognized or the parameters are invalid.

Extractor Pipeline

A flexible, extensible framework for extracting structured information from raw observational inputs (e.g., GONet camera files). The package organizes domain-specific extractors into a dependency-aware pipeline and returns a clean list of per-observation dictionaries ready for CSV/Parquet/JSON.

Overview

Dependency-aware execution: Each extractor declares the context it USES and PROVIDES. The runner executes them in a valid topological order.
Per-file alignment by filepath: Extractors that operate on files return a files list alongside their per-file columns. Results are merged via an inner join on the intersection of filepaths, guaranteeing that all per-file arrays remain aligned—even if some extractors skip (drop) problematic files.
Parallel extraction where it matters: Heavy pixel-level work (e.g., aperture statistics) runs in parallel while lightweight extractors (time, astronomy, weather) run sequentially.
Serializable outputs: Numpy types are converted to standard Python types, producing a list of JSON-serializable dicts (one per observation).

Public API

GONet_Wizard.GONet_utils.src.extractors.extract_all(file_list, channels, extraction_params, extractors=[<GONet_Wizard.GONet_utils.src.extractors.file_info.FileInfo object>, <GONet_Wizard.GONet_utils.src.extractors.time_info.TimeInfo object>, <GONet_Wizard.GONet_utils.src.extractors.astro_info.AstroInfo object>, <GONet_Wizard.GONet_utils.src.extractors.weather_info.WeatherInfo object>, <GONet_Wizard.GONet_utils.src.extractors.shape_info.ShapeInfo object>, <GONet_Wizard.GONet_utils.src.extractors.extraction_values.ExtractionValues object>])[source]

Run the extraction pipeline and return one row dictionary per observation.

Parameters:

file_list (list of str) – Input GONet image files. These paths are also used as the alignment key when merging per-file extractor outputs.
channels (list of str) – Image channels to process, for example ["red", "green", "blue"].
extraction_params (dict) – Shape and extraction settings passed to the pixel-statistics extractor. The dictionary must contain the shape fields required by GONet_Wizard.GONet_utils.src.extract_app.shapes.base.Shape.from_dict().
extractors (list of Extractor, optional) – Extractor instances to execute. Defaults to ALL_EXTRACTORS.

Return type:

List[Dict[str, Any]]

Returns:

list of dict – JSON-serializable row dictionaries. Each row corresponds to one file that survived all per-file extractor alignment steps.

Notes

Extractors that emit a "files" key are merged by filepath. If two extractors return different file subsets, only the intersection is retained so that all per-file columns stay aligned.

Core extractor framework

This module defines the small contract used by every extractor in the GONet pixel-extraction pipeline. Extractors are independent units that read a shared raw input dictionary, optionally read and update a shared context dictionary, and return a dictionary of extracted output fields.

The framework has two responsibilities:

provide the abstract Extractor interface used by concrete metadata and pixel-statistics extractors;
provide dependency ordering through sort_extractors(), using the Extractor.USES and Extractor.PROVIDES declarations.

Extractor outputs that contain one value per input file should include a "files" key. The runner and merge utilities use this key to align outputs from different extractors by filepath, even when an extractor skips a file.

Classes

Extractor: Abstract base class for all extraction pipeline components.
extraction_output: Dataclass containing pixel-statistics results for one masked region.

Functions

sort_extractors(): Topologically sort extractor instances from their declared dependencies.

class GONet_Wizard.GONet_utils.src.extractors.core.Extractor[source]

Bases: ABC

Base class for all extractors.

The Extractor class provides a framework for defining modular components that extract structured information from raw input data and shared context. Subclasses must implement the extract method and define the USES and PROVIDES attributes to declare dependencies and outputs.

USES

A list of context keys required by the extractor. These keys must be available in the shared context before the extractor runs.

Type:: list of str

PROVIDES

A list of context keys created or updated by the extractor. These keys are added to the shared context after the extractor runs.

Type:: list of str

Notes

The USES and PROVIDES attributes are used to determine the execution order of extractors in a pipeline. Extractors are executed in dependency order, ensuring that required context keys are available before an extractor runs.
Subclasses should focus on extracting specific types of information, such as metadata, time-based data, astronomical data, weather data, or pixel statistics.
The extract method must return a tuple containing:
- A dictionary of extracted fields.
- The updated shared context.

abstract extract(raw, context)[source]

Abstract method to extract structured information from raw input and shared context.

Subclasses must implement this method to define the logic for extracting specific types of information. It processes the raw input and shared context, returning extracted fields and the updated context.

Parameters:

raw (dict) – A dictionary containing raw input data. The structure of this dictionary depends on the specific extractor.
context (dict) – A shared dictionary for intermediate results. This dictionary is updated with the keys defined in the PROVIDES attribute.

Return type:

Tuple[Dict[str, Any], Dict[str, Any]]

Returns:

tuple – A tuple containing:

A dictionary of extracted fields.
The updated shared context.

Raises:

NotImplementedError – If the method is not implemented in a subclass.

class GONet_Wizard.GONet_utils.src.extractors.core.extraction_output(total_counts, mean_counts, std, npixels)[source]

Bases: object

Container for the results of a circular aperture extraction.

total_counts

Sum of pixel values within the circular region.

Type:: float

mean_counts

Average of the pixel values within the circle.

Type:: float

std

Standard deviation of the pixel values.

Type:: float

npixels

Number of pixels within the circular region.

Type:: int

GONet_Wizard.GONet_utils.src.extractors.core.sort_extractors(extractors)[source]

Topologically sort extractors based on their USES/PROVIDES dependencies.

Parameters:: extractors (list of Extractor) – Extractor instances to order.
Return type:: List[Extractor]
Returns:: list of Extractor – Ordered list that respects dependency requirements.
Raises:: RuntimeError – If there is a circular or unsatisfiable dependency.

Pipeline runner and public extraction API

This module provides the public orchestration entry point for the extraction subsystem. The main function, extract_all(), accepts a list of GONet image files, channel names, and shape/extraction parameters, then runs the configured extractor pipeline and returns one dictionary per retained file.

The runner combines two kinds of extractors:

lightweight metadata extractors, such as file, time, astronomy, weather, and shape metadata;
the heavier ExtractionValues extractor, which opens images and computes masked pixel statistics.

When ExtractionValues is present, it runs in a separate worker thread while the lightweight metadata extractors run sequentially. The individual outputs are merged through merge_extractor_into_data(), preserving filepath alignment via the "files" key.

GONet_Wizard.GONet_utils.src.extractors.runner.ALL_EXTRACTORS

Default extractor sequence used by extract_all().

Type:: list of Extractor

GONet_Wizard.GONet_utils.src.extractors.runner.Functions

---------

:func:`.extract_all`: Run the extraction pipeline and return JSON-serializable row dictionaries.

:func:`.convert_to_serializable`: Convert NumPy scalar/array objects to plain Python values.

GONet_Wizard.GONet_utils.src.extractors.runner.extract_all(file_list, channels, extraction_params, extractors=[<GONet_Wizard.GONet_utils.src.extractors.file_info.FileInfo object>, <GONet_Wizard.GONet_utils.src.extractors.time_info.TimeInfo object>, <GONet_Wizard.GONet_utils.src.extractors.astro_info.AstroInfo object>, <GONet_Wizard.GONet_utils.src.extractors.weather_info.WeatherInfo object>, <GONet_Wizard.GONet_utils.src.extractors.shape_info.ShapeInfo object>, <GONet_Wizard.GONet_utils.src.extractors.extraction_values.ExtractionValues object>])[source]

Run the extraction pipeline and return one row dictionary per observation.

Parameters:

file_list (list of str) – Input GONet image files. These paths are also used as the alignment key when merging per-file extractor outputs.
channels (list of str) – Image channels to process, for example ["red", "green", "blue"].
extraction_params (dict) – Shape and extraction settings passed to the pixel-statistics extractor. The dictionary must contain the shape fields required by GONet_Wizard.GONet_utils.src.extract_app.shapes.base.Shape.from_dict().
extractors (list of Extractor, optional) – Extractor instances to execute. Defaults to ALL_EXTRACTORS.

Return type:

List[Dict[str, Any]]

Returns:

list of dict – JSON-serializable row dictionaries. Each row corresponds to one file that survived all per-file extractor alignment steps.

Notes

Extractors that emit a "files" key are merged by filepath. If two extractors return different file subsets, only the intersection is retained so that all per-file columns stay aligned.

GONet_Wizard.GONet_utils.src.extractors.runner.convert_to_serializable(obj)[source]

Convert numpy objects to standard Python types for JSON serialization.

Parameters:: obj (Any) – The object to convert.
Return type:: Any
Returns:: Any – A JSON-serializable object.

Per-file alignment and extractor-result merging

Extractors may produce outputs for all files, a subset of files, or no per-file outputs at all. This module defines the merge rules used by the extraction runner to combine those outputs into a single accumulator without losing filepath alignment.

The convention is simple: an extractor result that contains per-file values must also contain a "files" key listing the filepath associated with each row. The first per-file extractor establishes the canonical file order. Later per-file extractors are inner-joined against that order, trimming previously stored per-file columns when necessary.

Functions

merge_extractor_into_data(): Merge one extractor output dictionary into the accumulator.

GONet_Wizard.GONet_utils.src.extractors.merge.merge_extractor_into_data(data, ext_results)[source]

Merge one extractor result dictionary into an aligned accumulator.

Parameters:

data (dict) – Mutable accumulator containing fields collected from previous extractors. If a previous per-file extractor has run, it contains a canonical "files" list.
ext_results (dict) – Output from one extractor. Per-file outputs must include a "files" key whose order matches all per-file vectors in ext_results.

Return type:

Dict[str, Any]

Returns:

dict – The same data object, updated in place and returned for convenience.

Notes

Scalar/global fields are copied directly. Per-file fields are aligned by filepath. When an extractor returns only a subset of the current canonical file list, the accumulator is reduced to the intersection of filepaths.

Pixel extraction and masked-region statistics

This module contains the extractor that performs the image-reading and pixel-statistics portion of the extraction workflow. Shape parameters are converted into a Shape, which produces a boolean mask for each image channel. The selected pixels are then summarized with total counts, mean counts, standard deviation, and pixel count.

The public ExtractionValues extractor processes many files in parallel. Source-mode runs use a process pool by default, while frozen desktop apps automatically use a thread pool because spawned process-pool workers are fragile inside PyInstaller bundles. The lower-level process_single_file() helper performs the work for one image and is useful for testing or debugging the extraction behavior on a single file.

Functions

extract_counts_from_region(): Compute summary statistics for an image array and boolean mask.
process_single_file(): Open one GONet file, remove overscan, build a shape mask, and extract channel statistics.

Classes

ExtractionValues: Extractor implementation used by the pipeline runner.

class GONet_Wizard.GONet_utils.src.extractors.extraction_values.ExtractionValues[source]

Bases: Extractor

Performs pixel count extraction for specified regions in image files.

This class inherits from the base Extractor class and implements methods to extract pixel count statistics from specified regions in image files.

USES

A list of context keys required by this extractor. For ExtractionValues, this is empty as it operates directly on the raw input.

Type:: list

PROVIDES

A list of keys that this extractor provides to the extraction pipeline. For ExtractionValues, this is empty as it only updates the shared context.

Type:: list

extract(raw, context)[source]

Extract masked pixel statistics for all requested files and channels.

Parameters:

raw (dict) –
Pipeline input dictionary. Required keys are:

"file_list"
List of GONet image paths.

"channels"
Channel names to extract from each image.

"extraction_parameters"
Shape parameters accepted by GONet_Wizard.GONet_utils.src.extract_app.shapes.base.Shape.from_dict().
context (dict) – Shared pipeline context. This extractor does not require or modify context entries.

Return type:

Tuple[Dict[str, Any], Dict[str, Any]]

Returns:

tuple – (results, context) where results contains a "files" list, exposure times, and one nested statistics dictionary per requested channel. The returned context is unchanged.

Notes

Files that cannot be opened or processed are skipped by process_single_file(). Downstream merging uses the returned "files" list to keep surviving rows aligned with other extractors.

GONet_Wizard.GONet_utils.src.extractors.extraction_values.extract_counts_from_region(data, mask)[source]

Compute statistics for pixels selected by a mask.

Parameters:

data (numpy.ndarray or list) – 2D image array.
mask (numpy.ndarray) – Boolean array of the same shape as data indicating which pixels to include.

Return type:

extraction_output

Returns:

extraction_output – Statistical summary of pixel values in the masked region.

GONet_Wizard.GONet_utils.src.extractors.extraction_values.process_single_file(gonet_file, channels, extraction_params)[source]

Process one image file and return channel statistics for one shape.

Parameters:

gonet_file (str) – Path to the image file to process.
channels (list of str) – Channel names to extract from the image.
extraction_params (dict) – Shape parameters accepted by GONet_Wizard.GONet_utils.src.extract_app.shapes.base.Shape.from_dict().

Return type:

dict

Returns:

dict or None – Per-file result dictionary, or None if the file cannot be loaded or processed. Successful results include the filepath, exposure time, and one statistics dictionary per channel. Each channel dictionary contains total_counts, mean_counts, std, and npixels fields.

Notes

The image is loaded with GONetFile.from_file(), overscan is removed, and the same shape mask is applied independently to each requested channel.

Filename metadata extractor

This module provides the FileInfo extractor, responsible for deriving basic observational metadata directly from filenames. It parses each filename to extract camera identifiers, Unix timestamps, and other basic attributes required to initialize the extraction context.

The extractor serves as the first stage in the pipeline, establishing the temporal reference for subsequent modules such as time, astronomy, and weather extractors.

Classes

FileInfo: Extracts metadata from filenames, such as camera ID and observation time.

class GONet_Wizard.GONet_utils.src.extractors.file_info.FileInfo[source]

Bases: Extractor

Extracts metadata from filenames.

This class inherits from the base Extractor class and is responsible for parsing filenames to extract relevant metadata such as camera ID and observation time.

USES

A list of dependencies required by this extractor. For FileInfo, this is empty as it operates directly on filenames.

Type:: list

PROVIDES

A list of keys that this extractor provides to the extraction pipeline. For FileInfo, this includes “time” and other metadata keys.

Type:: list

Notes

The filenames are expected to follow a specific format, such as: cameraID_timestamp.extension, where cameraID is an integer and timestamp is a Unix timestamp.

extract(raw, context)[source]

Extract metadata from filenames and update the shared context.

This method parses a list of filenames provided in the raw dictionary to extract metadata such as camera ID and observation time.

Parameters:

raw (dict) – A dictionary containing raw input data. Must include the key “file_list”, which is a list of filenames to process.
context (dict) – A shared dictionary for intermediate results. This is updated with the extracted metadata, including observation times.

Return type:

Tuple[Dict[str, Any], Dict[str, Any]]

Returns:

tuple – A tuple containing:

A dictionary with extracted metadata, including:
- camera (list of int): Camera IDs extracted from filenames.
- unix_time (list of int): Unix timestamps extracted from filenames.
- filename (list of str): Original filenames.
The updated context dictionary, which includes:
- time (astropy.time.Time): Observation times converted to astropy.Time.

Raises:

ValueError – If a filename does not follow the expected format.

Notes

The filenames are expected to follow the format cameraID_timestamp.extension.
This method uses astropy.time.Time to convert Unix timestamps to time objects for further processing.

Shape parameter extractor

This module defines the ShapeInfo extractor, which interprets and standardizes geometric parameters used for pixel count extraction.

It converts the raw extraction configuration into shape-specific metadata (e.g., circle radius, annulus width, center coordinates) using the base framework.

Classes

ShapeInfo: Extracts shape-specific parameters for pixel count extraction.

class GONet_Wizard.GONet_utils.src.extractors.shape_info.ShapeInfo[source]

Bases: Extractor

Extracts shape-specific parameters for pixel count extraction.

This class inherits from the base Extractor class and is responsible for processing shape-related extraction parameters.

USES

A list of context keys required by this extractor. For ShapeInfo, this is empty as it operates directly on the raw input.

Type:: list

PROVIDES

A list of keys that this extractor provides to the extraction pipeline. For ShapeInfo, this is empty as it only updates the shared context.

Type:: list

extract(raw, context)[source]

Extract shape-specific parameters and update the shared context.

This method processes the extraction parameters provided in raw[“extraction_parameters”] to dynamically instantiate a Shape object and retrieve its metadata. While the raw dictionary contains generic parameters, their geometric meaning is determined by the specific shape type. The correct keys for the output dictionary are defined in each shape class.

Parameters:

raw (dict) – A dictionary containing raw input data. Must include the key “extraction_parameters”, which is a dictionary of parameters specific to the shape. These parameters may include generic values (e.g., “radius”, “center”) that are mapped to shape-specific labels once the shape is determined.
context (dict) – A shared dictionary for intermediate results. This extractor does not modify the context.

Return type:

Tuple[Dict[str, Any], Dict[str, Any]]

Returns:

tuple – A tuple containing:

A dictionary with shape-specific metadata, including keys required for pixel count extraction.
The unchanged context dictionary.

Raises:

ValueError – If the extraction_parameters key is missing or invalid in the raw input.

Notes

The extraction_parameters dictionary must include a shape key specifying the type of shape.
Generic parameters in extraction_parameters (e.g., “param1”, “param2”) are mapped to shape-specific labels (e.g., “inner_radius”, “outer_radius”) based on the shape

Time metadata extractor

This module defines the TimeInfo extractor, responsible for deriving comprehensive time-related metadata from an astropy.time.Time object.

It converts raw observation timestamps into multiple temporal representations, including UTC and local ISO-formatted datetimes, Modified Julian Date (MJD), and both string and fractional time-of-day formats. The extractor also defines a unique “night” tag used to group observations belonging to the same local night.

Classes

TimeInfo: Extracts time-based information, including UTC and local timestamps, MJD, and time-of-day.

class GONet_Wizard.GONet_utils.src.extractors.time_info.TimeInfo[source]

Bases: Extractor

Extracts time-based information.

This class inherits from the base Extractor class and is responsible for processing time-related metadata from an astropy.time.Time object provided in the shared context.

USES

A list of context keys required by this extractor. For TimeInfo, this includes “time”, which must be an astropy.time.Time object.

Type:: list

PROVIDES

A list of keys that this extractor provides to the extraction pipeline. For TimeInfo, this is empty as it only updates the shared context.

Type:: list

extract(raw, context)[source]

Extract time-based metadata and update the shared context.

This method processes an astropy.time.Time object provided in the shared context to compute various time-related metadata, including UTC and local timestamps, Modified Julian Date (MJD), and time-of-day information.

Parameters:

raw (dict) – A dictionary containing raw input data. This extractor does not use the raw dictionary directly.
context (dict) – A shared dictionary for intermediate results. Must include the key “time”, which is an astropy.time.Time object.

Return type:

Tuple[Dict[str, Any], Dict[str, Any]]

Returns:

tuple – A tuple containing:

A dictionary with extracted time-based metadata, including:
night (str): Night tag derived from the first observation time.
date_utc (numpy.ndarray of str): UTC timestamps in ISO format.
date_local (numpy.ndarray of str): Local timestamps in ISO format.
mjd (numpy.ndarray of float): Modified Julian Date.
hours_utc (numpy.ndarray of str): Time-of-day in UTC (HH:MM:SS).
hours_local (numpy.ndarray of str): Time-of-day in local time (HH:MM:SS).
float_hours_utc (numpy.ndarray of float): Time-of-day in UTC as a fraction of a day.
float_hours_local (numpy.ndarray of float): Time-of-day in local time as a fraction of a day.
The updated context dictionary.

Raises:

ValueError – If the “time” key is missing or invalid in the context.

Notes

The time key in the context must be an astropy.time.Time object.
Time-of-day calculations are provided in both string (HH:MM:SS) and fractional formats.

Astronomical metadata extractor

This module defines the AstroInfo extractor, which computes basic astronomical parameters for each observation time.

Using the observer’s geographic location, it determines the Sun and Moon altitudes above the horizon and calculates the fractional lunar illumination. These quantities are useful for evaluating sky brightness conditions and contextualizing night-sky measurements.

Classes

AstroInfo: Computes solar and lunar altitudes and moon illumination for observation times.

class GONet_Wizard.GONet_utils.src.extractors.astro_info.AstroInfo[source]

Bases: Extractor

Computes solar and lunar altitudes and moon illumination.

This class inherits from the base Extractor class and is responsible for calculating astronomical metadata based on observation times.

USES

A list of context keys required by this extractor. For AstroInfo, this includes “time”, which must be an astropy.time.Time object.

Type:: list

PROVIDES

A list of keys that this extractor provides to the extraction pipeline. For AstroInfo, this is empty as it only updates the shared context.

Type:: list

extract(raw, context)[source]

Extract astronomical metadata.

This method computes the altitude of the Sun and Moon, as well as the fraction of the Moon illuminated, for each observation time provided in the shared context.

Parameters:

raw (dict) – A dictionary containing raw input data. This extractor does not use the raw dictionary directly.
context (dict) – A shared dictionary for intermediate results. Must include the key “time”, which is an astropy.time.Time object.

Return type:

Tuple[Dict[str, Any], Dict[str, Any]]

Returns:

tuple – A tuple containing:

A dictionary with extracted astronomical metadata, including:
sunaltaz (numpy.ndarray of float): Altitude of the Sun in degrees.
moonaltaz (numpy.ndarray of float): Altitude of the Moon in degrees.
moon_illumination (numpy.ndarray of float): Fraction of the Moon illuminated.
The updated context dictionary.

Raises:

ValueError – If the “time” key is missing or invalid in the context.

Notes

The time key in the context must be an astropy.time.Time object.

Weather metadata extractor

This module defines the WeatherInfo extractor, responsible for retrieving hourly meteorological conditions corresponding to each observation time.

It queries the local weather station defined in the environment configuration and interpolates the closest hourly record for each observation. The extractor provides standard meteorological fields such as temperature, dew point, humidity, pressure, wind speed, and categorical condition codes.

Classes

WeatherInfo: Fetches hourly weather conditions matched to observation times.

class GONet_Wizard.GONet_utils.src.extractors.weather_info.WeatherInfo[source]

Bases: Extractor

Fetches hourly weather conditions matched to each observation time.

This class inherits from the base Extractor class and is responsible for retrieving weather data such as temperature, humidity, wind speed, pressure, and condition codes for each observation time provided in the shared context.

USES

A list of context keys required by this extractor. For WeatherInfo, this includes “time”, which must be an astropy.time.Time object.

Type:: list

PROVIDES

A list of keys that this extractor provides to the extraction pipeline. For WeatherInfo, this is empty as it only updates the shared context.

Type:: list

extract(raw, context)[source]

Extract hourly weather data and update the shared context.

This method retrieves weather data for each observation time provided in the shared context. The weather data includes temperature, humidity, wind speed, pressure, and condition codes (see https://dev.meteostat.net/formats.html#weather-condition-codes). The data is matched to the closest hourly weather observation.

Parameters:

raw (dict) – A dictionary containing raw input data. This extractor does not use the raw dictionary directly.
context (dict) – A shared dictionary for intermediate results. Must include the key “time”, which is an astropy.time.Time object.

Return type:

Tuple[Dict[str, Any], Dict[str, Any]]

Returns:

tuple – A tuple containing:

A dictionary with extracted weather data, including:
temperature (numpy.ndarray of float): Temperature in degrees Celsius.
dew_point (numpy.ndarray of float): Dew point temperature in degrees Celsius.
wind_speed (numpy.ndarray of float): Wind speed in kilometers per hour.
pressure (numpy.ndarray of float): Atmospheric pressure in hectopascals (hPa).
humidity (numpy.ndarray of float): Relative humidity as a percentage.
condition_code (numpy.ndarray of int): Weather condition codes.
The updated context dictionary.

Raises:

ValueError – If the “time” key is missing or invalid in the context.

Notes

The time key in the context must be an astropy.time.Time object.
Weather data is fetched using the meteostat.Hourly API.
If no weather data is available for the requested time range, the method returns arrays filled with NaN values.

Extraction GUI

GONet Extraction GUI Entrypoint

This module defines the Dash application entry point for the GONet extraction GUI. The extraction GUI provides an interactive interface for defining regions of interest and extracting pixel counts from GONet image files.

As with the main dashboard, this GUI is no longer launched as a standalone Dash application. Instead, it is integrated into the centralized Dash orchestration layer provided by GONet_Wizard.ui.dash_runner. This allows the extraction GUI to be:

Launched from both CLI and HTML-based GUI contexts
Reused across multiple invocations without restarting the server
Embedded consistently within the unified Flask + pywebview UI runtime

This module is responsible only for describing how the extraction Dash app should be configured and launched. All lifecycle management is delegated to the shared Dash runner.

Functions

ensure_dashboard_running(): Public entry point used by CLI and GUI commands to launch (or reuse) the extraction GUI Dash server.

GONet_Wizard.GONet_utils.src.extract_app.extract_gui.mark_interactive_extraction_submitted()[source]

Mark the active interactive extraction session as intentionally submitted.

Return type:: None

GONet_Wizard.GONet_utils.src.extract_app.extract_gui.cancel_interactive_extraction_if_unsubmitted()[source]

Finish the form stream when the extraction window closes without Extract.

Closing the pywebview window via the title-bar X bypasses Dash callbacks. The launcher form is still waiting on its original streaming response, so this window-close hook emits the same final status that the explicit Exit button would have emitted. If the user clicked Extract, the worker thread owns the stream and this hook deliberately does nothing.

Return type:: None

GONet_Wizard.GONet_utils.src.extract_app.extract_gui.ensure_extraction_gui_running(data_files, debug, port=8051, channels=None, output=None, output_type=None, terminal_stream=None)[source]

Ensure the extraction GUI Dash server is running and return its URL.

This function is safe to call repeatedly. If a server instance for the extraction GUI is already running on the given port, it is reused. Otherwise, a new Dash server is started in a background thread using the centralized Dash runner.

Parameters:

data_files (list of str) – Paths to GONet image files to be used for extraction.
debug (bool) – Whether to run Dash in debug mode.
port (int, optional) – Localhost port to bind the Dash server to.
channels (list of str, optional) – Channels to extract when the user clicks the Extract button. If not provided, all standard GONet channels are extracted.
output (str, optional) – Output path requested by the caller. If not provided, the extraction callback writes the usual extraction_<shape>.json file.
output_type (str, optional) – Requested output type, either "json" or "csv".
terminal_stream (object, optional) – Stream bridge used by the launcher GUI terminal panel. When present, extraction callback output is forwarded to the original command stream.

Return type:

str

Returns:

str – The local URL of the extraction GUI (e.g. "http://127.0.0.1:8051").

Dash layout for the interactive extraction GUI.

This module defines the component tree used by the extraction application: file selection, image display, region controls, extraction options, and the stores used by callbacks. It is intentionally limited to structure and component IDs; visual presentation belongs in the shared CSS assets so the extraction GUI stays consistent with the rest of the GONet Wizard desktop interface.

The layout reads the initial file list from the Flask server configuration that is prepared by extract_server before the Dash app is launched.

GONet_Wizard.GONet_utils.src.extract_app.extract_layout.layout

Root Dash component assigned to the extraction app.

Type:: dash.development.base_component.Component

Defines the core interactivity for the GONet extraction GUI via Dash callbacks.

This module wires together user interactions with the UI elements defined in extract_layout.py. It updates the displayed image, overlays shape-based masks, computes extraction statistics, handles freehand drawing and path saving/loading, and manages the state of shape-specific components. It also registers a client-side callback for JSON downloads of the drawn region.

The shape-control logic is intentionally split into two callbacks: one callback updates only the sidebar labels, placeholders, and visibility classes, while a separate callback updates Plotly drawing mode and graph configuration. Keeping these concerns separate makes the parameter controls react immediately when the selected shape changes and avoids coupling simple UI label updates to figure configuration changes.

Functions

load_gonet_file():
Loads the GONet file for the selected file.
store_binning():
Stores the binning information for the current extraction.
update_figure_heatmap():
Update the heatmap figure based on the selected channel and binning option.
update_shape_options():
Updates the visible sidebar controls, labels, placeholders, and CSS classes based on the selected extraction shape.
update_shape_drawing_mode():
Updates the Plotly drag mode and drawing-toolbar configuration based on the selected extraction shape.
catch_drawn_path():
Captures the path of a freehand-drawn region and updates the figure.
activate_deactivate_freehand_buttons():
Enables or disables freehand drawing buttons based on the presence of a drawn path.
update_extraction_params():
Updates extraction parameters based on user inputs and interactions.
update_drawn_figure_and_extraction_values():
Draw the updated shape on the figure and display the extraction values.
save_path():
Prepares the freehand path data for saving when the “Save Path” button is clicked.
load_path():
Loads a previously saved freehand path from uploaded JSON content.
update_extract_button_disabled():
Enables the interactive Extract button only after the selected shape is valid.
extraction_button():
Validates extraction parameters, closes the setup window, and starts extraction.
exit_app():
Requests closing the PyWebView window when the “Exit” button is clicked.

Notes

Shapes supported: circle, rectangle, annulus, freehand.
Statistics returned: total counts, mean, std dev, and number of selected pixels.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.load_gonet_file(selected_file)[source]

Load the GONet file for the selected file.

The GONet file is loaded server-side, for faster access. This callback runs automatically when the app loads. This ensures that the file is loaded properly and spawns all other necessary initializing callbacks.

Parameters:

selected_file (str) – The name of the file selected in the file dropdown.

Returns:

tuple – A tuple containing:

Serverside: The loaded GONet as a GONetFile object.
str: An empty string to update the file-loaded component, which serves as control for the loading state.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.store_binning(binning)[source]

Store the selected binning option as a more convenient int.

This callback stores the selected binning option in a dcc.Store component. The stored value can be used by other callbacks to adjust image processing based on the user’s choice. The bin dcc.Store component is initialized in the layout, so it is available for use since the app starts.

Parameters:: binning (str) – The binning option selected in the binning dropdown. Possible values are “1x1”, “2x2”, and “4x4”.
Returns:: int – The selected binning option to be stored in the bin store.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.update_figure_heatmap(_, selected_channel, bin, gof, fig)[source]

Update the heatmap figure based on the selected channel and binning option.

This callback updates the gonet-image figure to display the image data corresponding to the selected channel and binning option. The image data is loaded using the GONetFile class, which extracts the specified channel from the selected file. When the figure is binned, the axis maintains the original unbinned pixel coordinates. Hovering over the figure will show the original pixel coordinates in the tooltip.

To ensure the correct sequence of callbacks when the app loads for the first time, this callback waits on the file-loaded component to be updated before executing.

Parameters:

_ (str or NoneType) – Dummy Div triggered by update_figure() when the figure is ready (ignored).
selected_channel (str) – The name of the channel selected in the channel dropdown. Possible values are “red”, “green”, and “blue”.
bin (int) – The binning option selected in the binning dropdown. Possible values are 1, 2, and 4.
gof (GONetFile) – The GONet file currently loaded server-side.
fig (dict) – The current figure object for the gonet-image component, which is updated with the new image data.

Returns:

tuple – A tuple containing:

dict: The updated figure object with the new image data.
str: An empty string to update the heatmap-ready-control component and signal that the figure update is complete.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.update_shape_options(selected_shape)[source]

Update visible shape-specific controls when the selected shape changes.

This callback is responsible only for the sidebar control state. It switches between the geometric-parameter panel and the freehand-drawing panel, updates the label for the shape-specific parameter row, and controls whether the second shape parameter is visible.

The callback uses CSS class names rather than inline style dictionaries because the extraction GUI presentation is centralized in the shared static stylesheet. In particular, the second parameter is hidden by applying the hidden class to the parameter container, not to the input itself. This keeps both the layout and the callback aligned with the current styled extraction UI.

Parameters:

selected_shape (str) – The extraction shape selected by the shape-selector radio items. Expected values are "circle", "rectangle", "annulus", and "freehand".

Returns:

tuple – A tuple containing:

str: CSS classes for the geometric shape-options panel.
str: CSS classes for the freehand-options panel.
str: Label text for the shape-specific parameter row.
str: Placeholder text for the first shape parameter input.
str: CSS classes for the second shape parameter container.
str: Placeholder text for the second shape parameter input.

Notes

The visibility behavior is:

circle shows one parameter, interpreted as radius.
rectangle shows two parameters, interpreted as side lengths.
annulus shows two parameters, interpreted as inner and outer radius.
freehand hides the geometric parameter panel and shows the drawing controls instead.

This callback is intentionally independent from update_shape_drawing_mode(), so that basic parameter-label updates do not depend on Plotly graph configuration updates.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.update_extract_button_disabled(selected_shape, center_x, center_y, param1, param2, start_angle, end_angle, path)[source]

Disable the Extract button until interactive parameters are valid.

Parameters:

selected_shape (str) – Current extraction shape selected in the interactive app.
center_x (float or None) – Shape center coordinates.
center_y (float or None) – Shape center coordinates.
param1 (float or None) – Shape-specific parameters.
param2 (float or None) – Shape-specific parameters.
start_angle (float or None) – Optional angular sector limits.
end_angle (float or None) – Optional angular sector limits.
path (str or None) – Freehand path data.

Returns:

bool – True when the button should be disabled, False when the parameters are complete enough to run extraction.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.update_shape_drawing_mode(_, selected_shape, fig, config)[source]

Update Plotly drawing mode and graph configuration for the selected shape.

This callback controls the interactive behavior of the image graph. For geometric shapes, the graph stays in normal zoom mode. For freehand extraction, the Plotly closed-path drawing tool is enabled and the graph drag mode is switched to "drawclosedpath".

The callback also updates config-done-dummy-div as a synchronization signal for downstream extraction-parameter updates. This keeps parameter recomputation ordered after graph configuration changes when the app first loads or when the selected shape changes.

Parameters:

_ (str or None) – Dummy value from heatmap-ready-control. The value itself is ignored; the input is used to ensure the image figure has been initialized before drawing-mode configuration is applied.
selected_shape (str) – The extraction shape selected by the shape-selector radio items. Expected values are "circle", "rectangle", "annulus", and "freehand".
fig (dict or None) – Current Plotly figure dictionary for the gonet-image graph.
config (dict or None) – Current Plotly graph configuration dictionary.

Returns:

tuple – A tuple containing:

dict or dash.no_update: Updated Plotly figure, or dash.no_update when the drag mode did not change.
dict or dash.no_update: Updated Plotly graph config, or dash.no_update when the configuration did not change.
str: Dummy synchronization value used by callbacks that recompute extraction parameters.

Notes

The callback avoids unnecessary graph updates when the requested drag mode is already active. This is especially useful when switching among geometric shapes, since circle, rectangle, and annulus all use Plotly zoom mode.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.catch_drawn_path(relayout_data, reset_button, fig)[source]

Capture the path of a freehand-drawn region and update the figure.

This callback listens for changes in the relayoutData property of the gonet-image figure, which contains information about shapes drawn by the user. It captures the path of the most recently drawn shape and updates the figure layout accordingly. If the “Reset” button is clicked, all drawn shapes are cleared.

Parameters:

relayout_data (dict or NoneType) – Data from the relayoutData property of the gonet-image figure, containing information about drawn shapes. This includes the path key for freehand-drawn regions.
reset_button (int or NoneType) – Click count of the “Reset” button for freehand drawing. Used to determine if the user has requested to clear all drawn shapes.
fig (dict) – The current figure object for the gonet-image component, which is updated with the new shape or cleared shapes.

Returns:

tuple – A tuple containing:

str or NoneType: The path of the most recently drawn shape, or None if the shapes are cleared.
dict: The updated figure object with the new shape or cleared shapes.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.activate_deactivate_freehand_buttons(path)[source]

Enable or disable freehand drawing buttons based on the presence of a drawn path.

This callback controls the state of the “Reset” and “Save” buttons for freehand drawing. If a path is present in the drawn-path store, the buttons are enabled. Otherwise, they remain disabled.

Parameters:: path (str or NoneType) – The current freehand path data stored in the drawn-path store. If None, no path is present, and the buttons will be disabled.
Returns:: tuple – A tuple containing: - bool: Whether the “Reset” button should be disabled. - bool: Whether the “Save” button should be disabled.

Notes

The “Reset” button clears the current freehand path when clicked.
The “Save” button allows the user to save the current freehand path to a file.
Both buttons are disabled when no path is present.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.update_extraction_params(_, center_x, center_y, param1, param2, start_angle, end_angle, path, selected_shape, gof, channel, masked_figure, error_banner_class)[source]

Update extraction parameters based on user inputs.

This callback updates the extraction-params store with the current values of the shape parameters entered by the user or with the latest freehand path. The updated extraction parameters are then used to generate the mask for the selected shape, which is stored in the mask component. Using this mask, the extracted values are computed and stored in the extracted-values component.

This callback also handles any errors that may occur with invalid parameters, by displaying an error message in the error-banner component. The error message will be displayed only once all the parameters have been validated, and not for every single parameter input.

Parameters:

_ (str or NoneType) – The value of the config-done-dummy-div component, which indicates when the figure configuration is complete. This guarantees that the figure’s configuration is fully updated before any subsequent extraction gets triggered by the extraction-params component.
center_x (float or NoneType) – X-coordinate of the shape center (if applicable).
center_y (float or NoneType) – Y-coordinate of the shape center (if applicable).
param1 (float or NoneType) – First shape-specific parameter (e.g., radius, side length, inner radius).
param2 (float or NoneType) – Second shape-specific parameter (e.g., side length, outer radius).
start_angle (float or NoneType) – Start angle for sector shapes (in degrees).
end_angle (float or NoneType) – End angle for sector shapes (in degrees).
selected_shape (str) – The currently selected shape type from the dropdown. Possible values are “circle”, “rectangle”, “annulus”, and “freehand”.
path (str or NoneType) – The current freehand path data stored in the drawn-path store.
gof (GONetFile) – The GONet file currently loaded server-side.
channel (str) – The currently selected channel from the channel-selector component.
masked_figure (list) – The current masked figure data stored in the mask store.
error_banner_class (str) – The current CSS classes for the error banner.

Returns:

tuple – A tuple containing:

dict with updated extraction parameters.
list with the updated masked figure data.
Serverside the extraction_output object with the extracted values.
str with any error messages for the banner.
str with the updated visibility class for the error banner.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.update_drawn_figure_and_extraction_values(extraction_params, fig, mask, extracted_values)[source]

Draw the updated shape on the figure and display the extraction values.

This callback draws the new shape and display the pixel statistics (total counts, mean, standard deviation, and pixel count) for the region defined by the current extraction parameters and the drawn path.

Parameters:

extraction_params (dict) – The current extraction parameters stored in the extraction-params store. This includes the shape type, center coordinates, dimensions, angles, and the drawn path (if applicable).
fig (dict) – The current figure object for the gonet-image component, which contains the image data used for the extraction.
mask (list) – The current mask data stored in the mask store.
extracted_values (ExtractionOutput) – Object containing the extracted values.

Returns:

tuple – A tuple containing: - dict: The updated figure object for the gonet-image component. - int: Total pixel counts within the selected region. - float: Mean pixel value within the selected region. - float: Standard deviation of pixel values within the selected region. - int: Number of pixels within the selected region.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.save_path(_, path)[source]

Callback to prepare the freehand path data for saving.

This function is triggered when the “Save Path” button is clicked. It returns the currently drawn path so that it can be serialized and downloaded via a client-side callback.

Parameters:

_ (int or NoneType) – Click count of the “Save Path” button (ignored).
path (str or NoneType) – The path of the freehand-drawn region, if applicable. If None, no freehand region is used.

Returns:

list – The same path object, to be passed to the save-path store for download.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.load_path(contents)[source]

Load a previously saved freehand path from uploaded JSON content.

This callback is triggered when the user uploads a JSON file via the upload component. The uploaded file is parsed, and the freehand path data is loaded into the drawn-path store. The extraction parameters are updated to include the loaded path.

Parameters:

contents (str) – Base64-encoded contents of the uploaded JSON file, as returned by Dash’s dcc.Upload component. The file must contain valid JSON data representing the freehand path.

Returns:

tuple – A tuple containing:

dict: Updated extraction parameters with the loaded path.
str: An empty string to update the config-done-dummy-div component, which serves as control for the extraction-params component.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.extraction_button(_, extraction_params, path, selected_shape, n)[source]

Validate parameters, close the setup window, and start extraction.

This callback is triggered when the user clicks the “Extract” button in the interactive extraction window. It validates the current parameters before closing the window, starts the extraction in a worker thread, and lets the main GUI terminal stream or CLI terminal report progress and completion.

Parameters:

_ (int or None) – The number of times the “Extract” button has been clicked. This parameter is unused but required by Dash as the input trigger.
extraction_params (dict) – The extraction parameters retrieved from the extraction-params dcc.Store component in the Dash layout.
path (str or NoneType) – The path of the freehand-drawn region, if applicable. If None, no freehand region is used.
selected_shape (str) – Current value of the shape selector. Used to keep freehand extraction parameters synchronized with the drawn path.
n (int or None) – The current number of clicks on the “Exit” button.

Returns:

tuple – A tuple containing the exit-click update and error-banner contents/classes. On success, the setup window closes immediately while extraction continues. On failure, the window remains open and the error banner reports the validation error.

GONet_Wizard.GONet_utils.src.extract_app.extract_callbacks.exit_app(_)[source]

Callback to request closing the PyWebView window when the “Exit” button is clicked.

This callback sends a JavaScript command to the embedded PyWebView browser, which calls the exposed Python API method close_window() to close the window.

Parameters:: _ (int or NoneType) – Click count of the “Exit” button (ignored).
Returns:: bool – Always returns True to disable the “Exit” button after it has been clicked.

Defines the Flask server and Dash app instance used by the GONet extraction GUI, and configures server-side state via dash-extensions.

This module initializes:

a flask.Flask backend server named GONet Wizard extraction GUI,
a dash_extensions.enrich.DashProxy app with dash_extensions.enrich.ServersideOutputTransform enabled, so large Python objects (e.g., NumPy arrays) can be kept server-side and never serialized to the browser,
a filesystem cache directory file_system_backend/ used by the default dash-extensions backend for storing server-side objects,
startup and exit cleanup of that cache directory to prevent stale files and uncontrolled growth during local runs.

This app is intended for local, single-user use. Clearing the cache on startup/exit is a simple way to avoid disk accumulation and stale objects when users load new data repeatedly. If you later require persistence across runs or multi-process deployments, consider a networked backend (e.g., Redis) and remove the auto-cleanup.

GONet_Wizard.GONet_utils.src.extract_app.extract_server.server

The Flask backend used by the Dash application.

Type:: flask.Flask

GONet_Wizard.GONet_utils.src.extract_app.extract_server.app

The Dash app instance configured with server-side output support.

Type:: dash_extensions.enrich.DashProxy