thalianacv.utils package

Submodules

thalianacv.utils.logging module

Logging configuration and base exception for thalianacv.

This module provides a consistently configured logger factory and the base exception class used across the package. All submodules should obtain their logger via get_logger() rather than calling logging.getLogger() directly, so that handler and formatter configuration is applied uniformly.

Example

>>> from thalianacv.utils.logging import get_logger, ThalianaCVError
>>> logger = get_logger(__name__)
>>> logger.info("Pipeline started")

thalianacv.utils.logging.get_logger(name: str) → Logger

Return a consistently configured logger for the given name.

Creates a logger with a stdout StreamHandler and a standard formatter if one has not already been attached. Safe to call multiple times with the same name — returns the existing logger on subsequent calls.

Parameters:

name – Logger name, typically __name__ of the calling module.

Returns:

Configured logging.Logger instance.

Example

>>> logger = get_logger(__name__)
>>> logger.info("Starting inference")

exception thalianacv.utils.logging.ThalianaCVError

Bases: Exception

Base exception for all thalianacv errors.

Raise this or a subclass whenever the package needs to signal a recoverable or unrecoverable error to the caller. Catching this base class is sufficient to handle any package-level exception.

Example

>>> raise ThalianaCVError("Model weights not found at path: /tmp/model.h5")

thalianacv.utils.types module

Shared type definitions for thalianacv.

This module defines the core data structures used across the package. All submodules that produce or consume prediction results should import from here rather than defining their own types.

Note

PredictionResult is an internal dataclass, not a Pydantic model. To serialise it for an HTTP response, define a Pydantic response model in thalianacv.api that mirrors these fields. When converting:

• shoot_mask and root_mask are numpy arrays, convert with .tolist()

• coordinates is a pandas DataFrame, convert with .to_dict(“records”)

• confidence_score is a plain float and needs no conversion

A Pydantic response model should be defined in thalianacv.api with fields shoot_mask, root_mask, coordinates, and confidence_score.

class thalianacv.utils.types.PredictionResult(shoot_mask: ndarray, root_mask: ndarray, coordinates: DataFrame, confidence_score: float)

Bases: object

Output of a single inference run on a plant image.

This is the internal contract between thalianacv.core and all consumers (API, CLI, database). All fields are populated by predict() in thalianacv.core.predict.

When predict() is running as a stub, fields contain sentinel values that are impossible in real output, making stubs easy to detect. shoot_mask and root_mask are arrays filled with -1, coordinates is a DataFrame with correct columns and all values set to -999.0, and confidence_score is -1.0.

shoot_mask: ndarray

root_mask: ndarray

coordinates: DataFrame

confidence_score: float

static empty_coordinates() → DataFrame

Return a stub coordinates DataFrame with sentinel values.

Returns a valid DataFrame with the correct column structure and 5 rows, all numeric values set to -999.0. Used by predict() stub and as a reference for the expected DataFrame schema.

Returns:

DataFrame with 5 rows and all expected coordinate columns.

Module contents

Shared utilities for thalianacv.

This submodule provides logging, error handling, and type definitions used across the package. All submodules should import from here rather than from the individual modules directly.