P2DingoCV.HotspotLogic.HotspotDetector

Classes

HotspotDetector(cam, exitPath[, config])

Abstract base class for hotspot detection in thermal or visual frames.
class P2DingoCV.HotspotLogic.HotspotDetector.HotspotDetector(cam, exitPath, config=None)[source]

Bases: object

Abstract base class for hotspot detection in thermal or visual frames.

This class provides core utilities for detecting hotspots using clustering, contrast analysis, and shape metrics. Specific hotspot detection strategies should be implemented in subclasses by overriding execute().

Parameters:
cam

The camera object used to read in frames.

Type:

Camera

outputPath

Directory where results and diagnostics will be saved.

Type:

str

utility

Utility object for saving and plotting diagnostics.

Type:

VisualUtils

labFrame

Current frame converted to CIELAB color space.

Type:

Frame

frame

Current raw frame in BGR format.

Type:

np.ndarray

frameArea

Total number of pixels in the frame.

Type:

int

frameCount

Number of frames processed.

Type:

int

k

Number of clusters for k-means segmentation.

Type:

int

clusterJoinKernel

Kernel size for morphological joining of clusters.

Type:

int

hotSpotThreshold

Score threshold for hotspot classification.

Type:

float

sigmoidSteepnessDeltaP

Steepness parameter for ΔP sigmoid scaling.

Type:

float

sigmoidSteepnessZ

Steepness parameter for Z-score sigmoid scaling.

Type:

float

compactnessCutoff

Normalization cutoff for compactness.

Type:

float

dilationSize

Kernel dilation factor for contrast calculation.

Type:

int

wDeltaP

Weight for ΔP score in final hotspot scoring.

Type:

float

wZscore

Weight for Z-score in final hotspot scoring.

Type:

float

wCompactness

Weight for compactness in final hotspot scoring.

Type:

float

wAspectRatio

Weight for aspect ratio in final hotspot scoring.

Type:

float

wEccentricity

Weight for eccentricity in final hotspot scoring.

Type:

float

pixelCounts

Pixel counts per cluster from k-means.

Type:

np.ndarray

colours

List of BGR colours for visualization.

Type:

list[tuple[int, int, int]]

__init__(cam, exitPath, config=None)[source]
Parameters:
Return type:

None

classifyHotspot(frame, mask, saveVisuals)[source]

Classify and score hotspots from a clustered mask.

Parameters:

  • frame (np.ndarray) – Original BGR frame.

  • mask (np.ndarray) – Binary mask of hotspot candidate regions.

  • saveVisuals (bool) – Whether to save annotated hotspot frames.

Returns:

  • Sorted list of hotspot data tuples, containing: (label, score, temp, centroid, ΔPscore, ΔP, z, zNorm, compactness, aspect ratio, eccentricity, area).

  • Boolean indicating whether any hotspot exceeds threshold.

Return type:

tuple[list, bool]

abstractmethod execute()[source]

Run the main hotspot detection process.

This method must be implemented in subclasses to define the specific detection strategy.

Raises:

NotImplementedError – If called on the base class directly.

filterMask(mask)[source]

Filter out noise regions from a binary mask.

Parameters:

mask (np.ndarray) – Input binary mask.

Returns:

Filtered mask containing only valid regions.

Return type:

np.ndarray

hotSpotScore(deltaPScore, zScoreNorm, compactness, aspectRatio, eccentricity)[source]

Compute a weighted hotspot score.

Parameters:

  • deltaPScore (float) – Probability score from robust ΔP.

  • zScoreNorm (float) – Normalized Z-score.

  • compactness (float) – Compactness of the hotspot region.

  • aspectRatio (float) – Aspect ratio of the hotspot region.

  • eccentricity (float) – Eccentricity of the hotspot region.

Returns:

Final weighted hotspot score.

Return type:

float

kMeansThermalGrouping(frame, saveDiagonstics)[source]

Cluster pixels into thermal groups using k-means.

Parameters:

  • frame (Frame) – Input frame in BGR format.

  • saveDiagonstics (bool) – Whether to save segmented outputs.

Returns:

Binary mask for the most intense cluster.

Return type:

Frame

loadConfig(configPath)[source]

Load hotspot detector parameters from a JSON configuration file.

This will overwrite the default tunable parameters set in __init__.

Parameters:

  • config_path (str) – Path to the JSON configuration file.

  • configPath (str)

Raises:

  • FileNotFoundError – If the config file does not exist.

  • json.JSONDecodeError – If the config file is not valid JSON.

Return type:

None

perFrameProcessing(frame, saveFrames, diagonstics)[source]

Process a single frame through the hotspot detection pipeline.

Parameters:

  • frame (Frame) – Input image frame in BGR format.

  • saveFrames (bool) – Whether to save visual outputs.

  • diagonstics (bool) – Whether to save intermediate diagnostic results.

Returns:

  • List of hotspot detection results for this frame.

  • Boolean indicating whether a hotspot was detected.

Return type:

tuple[list, bool]

perFrameSetup(frame)[source]

Initialize state for a new frame.

Resets internal counters, computes frame area, and sets up per-frame parameters.

Parameters:

frame (Frame) – Input frame in BGR format.

Returns:

The original frame after setup.

Return type:

Frame

pixelContrast(LChannel, componentMask, otherHotspotsMask, area)[source]

Compute contrast metrics for a hotspot region.

Parameters:

  • LChannel (Frame) – Luminance channel of LAB frame.

  • componentMask (Frame) – Mask of the region of interest.

  • otherHotspotsMask (Frame) – Mask of other hotspots to exclude.

  • area (float) – Pixel area of the region.

Returns:

  • Robust ΔP contrast.

  • Global Z-score.

  • ΔP probability score.

  • Normalized Z-score.

Return type:

tuple[float, float, float, float]

pixelToTemp(pixelVal)[source]

Convert a pixel value to temperature using calibration.

Parameters:

pixelVal (float) – Pixel luminance value.

Returns:

Estimated temperature.

Return type:

float

Raises:

TempDetectionFailed – If calibration parameters are missing.

processingDiagonstics()[source]

Plot diagnostic data such as pixel count distributions.

Saves plots to the configured output path.

Return type:

None

resetFrameData()[source]

Reset frame-dependent state variables.

Resets temperature calibration, frame buffers, and cluster statistics.

Return type:

None

shapeAndCompactness(componentMask, area)[source]

Calculate shape metrics for a region.

Parameters:

  • componentMask (Frame) – Binary mask of a connected component.

  • area (float) – Pixel area of the component.

Returns:

  • Normalized compactness.

  • Aspect ratio.

  • Eccentricity (or aspect ratio if ellipse fitting fails).

Return type:

tuple[float, float, float]