OCR API

What discover_redaction_zones() and scan_pixel_content() build on. Everything on this page is documented but internal (see API stability), except DiscoveryResult.filter(), to_zones() and to_dataframe(), which are frozen at 1.0.

Zone discovery

session.discover_redaction_zones() returns a DiscoveryResult, which holds one DiscoveryCandidate per text region read at or above min_confidence.

DiscoveryResult

Holds the raw results of a discovery scan and provides methods to filter and group them into actionable redaction zones.

filter(predicate=0.0)

Returns a new result with filtered candidates.

Parameters:

Name	Type	Description	Default
predicate	Union[float, Callable]	Either a float, the minimum confidence kept (default 0.0, which keeps every candidate), or a callable that takes a DiscoveryCandidate and returns True to keep it.	0.0

Returns:

Type	Description
DiscoveryResult	The kept candidates, with the same source count.

to_zones(pad_x=20, pad_y=10, min_occurrence=0.1)

Groups candidates into suggested redaction zones.

Parameters:

Name	Type	Description	Default
pad_x	int	Horizontal padding for merging (higher values merge words on same line).	20
pad_y	int	Vertical padding.	10
min_occurrence	float	Fraction of valid sources (0.0-1.0) required to suggest a zone.	0.1

Returns:

Type	Description
List[Dict[str, Any]]	One dict per zone: zone as [y1, y2, x1, x2], type (LIKELY_NAME, PROPER_NOUN or TEXT), occurrence, mean confidence, and up to three examples. Zones 5 pixels or less wide or tall are dropped.

to_dataframe()

Returns a pandas DataFrame of the candidates, one row per candidate.

Returns:

Type	Description
pandas.DataFrame	One column per DiscoveryCandidate field.

Raises:

Type	Description
ImportError	If pandas is not installed.

DiscoveryCandidate dataclass

A single text region detected during discovery.

Attributes:

Name	Type	Description
text	str	The text OCR read.
confidence	float	OCR confidence, 0 to 100.
box	List[int]	[x, y, w, h] in pixels. A redaction zone is spelled differently, [y1, y2, x1, x2]; to_zones() converts.
source_index	int	Which sampled instance it was read from, counting only the instances that could be read.
classification	str	TEXT, NAME_PATTERN, PROPER_NOUN or PROPER_NOUN_CANDIDATE.

ZoneDiscoverer

Utilities for analyzing text regions and classifying them.

group_boxes(boxes, padding=0, pad_x=None, pad_y=None) staticmethod

Groups boxes into overlapping clusters.

Parameters:

Name	Type	Description	Default
boxes	List[List[int]]	Boxes as [x, y, w, h].	required
padding	int	Padding on both axes, used where pad_x or pad_y is not given.	0
pad_x	int	Horizontal padding when testing overlap.	None
pad_y	int	Vertical padding when testing overlap.	None

Returns:

Type	Description
List[List[int]]	The indexes into boxes of each cluster.

Verification

RedactionVerifier

Verifies pixel redaction strategies by comparing OCR results against configured redaction zones.

__init__(rules=None)

Parameters:

Name	Type	Description	Default
rules	List[Dict]	A list of redaction rules (config['machines']).	None

get_matching_rule(equipment)

Finds the redaction rule that applies to this equipment.

Exact Serial Number match only; the first matching rule wins.

Parameters:

Name	Type	Description	Default
equipment	Equipment	The instance's equipment, or None.	required

Returns:

Type	Description
Dict[str, Any]	The rule dictionary, or None when there is no equipment, no serial, or no rule for it.

is_covered(text_box, zone_box, threshold=0.5)

Checks if the text_box is significantly covered by the zone_box.

Parameters:

Name	Type	Description	Default
text_box	Tuple[int, int, int, int]	OCR box space (x, y, w, h).	required
zone_box	Tuple[int, int, int, int]	zone space (y1, y2, x1, x2), as redaction_zones entries are stored and as redaction applies them.	required
threshold	float	Fraction of text area that must be covered (0.0 - 1.0).	0.5

Returns:

Type	Description
bool	True if covered.

verify_instance(instance, equipment=None)

Runs OCR on the instance and classifies each text region.

• If text is fully matched (>= 80% coverage): considered Safe (Ignored).
• If text is partially matched (> 0% but < 80%): Reported as PARTIAL_LEAK.
• If text is not matched (0%): Reported as NEW_LEAK.

Text of two characters or fewer is skipped as noise.

Parameters:

Name	Type	Description	Default
instance	Instance	The instance to read.	required
equipment	Equipment	Selects the redaction rule by serial number; with none, every region is a NEW_LEAK.	None

Returns:

Type	Description
List[PhiFinding]	One finding per leaked region. Also [] when OCR is unavailable, which is not "nothing leaks": Session.scan_pixel_content() checks first and refuses instead.

Automation

ConfigAutomator

Analyzes OCR findings and generates suggestions to update the redaction configuration.

suggest_config_updates(report, _current_config) staticmethod

Generates a list of suggested configuration changes.

A NEW_LEAK finding suggests its text box as a new zone; a PARTIAL_LEAK finding suggests growing its best-matching zone to cover the text. A finding with no rule_serial in its metadata gets no suggestion. Zones are in config space, (y1, y2, x1, x2), the order every consumer of redaction_zones reads; OCR boxes arrive as (x, y, w, h) and are converted.

Parameters:

Name	Type	Description	Default
report	PhiReport	Findings from a pixel scan, each carrying leak_type, text_box, best_zone and rule_serial in its metadata.	required

Returns:

Type	Description
List[Dict[str, Any]]	One dict per suggestion, with serial, action and reason; an ADD_ZONE suggestion carries zone, an EXPAND_ZONE one original_zone and new_zone, each [y1, y2, x1, x2].

Pixel analysis

isocenter.pixel_analysis

OCR over pixel data: find burned-in text and where it sits.

TextRegion dataclass

Represents a region of text detected within an image or frame.

Attributes:

Name	Type	Description
text	str	The detected text string.
box	Tuple[int, int, int, int]	The bounding box of the text region (x, y, w, h).
confidence	float	The confidence score of the detection (0-100).
frame_index	int	The index of the frame where the text was detected (default 0).

analyze_pixels(instance)

Analyzes the pixel data of a DICOM Instance for burned-in text.

A load or OCR failure is logged at ERROR and what was read is returned. A frame this call loaded is released before it returns, with unload_pixel_data(); one that was resident before the call is left as it was. A caller who wants the frame afterwards calls instance.get_pixel_data().

Parameters:

Name	Type	Description	Default
instance	Instance	The instance to read.	required

Returns:

Type	Description
List[TextRegion]	Raw findings, not filtered against any zone. Also [] when OCR is unavailable or nothing could be read, so [] is not "no text"; the Session methods check availability first and report what this only logs.

detect_text_regions(pixel_data, frame_idx=0)

Runs OCR on the provided pixel data and returns text regions with bounding boxes.

Parameters:

Name	Type	Description	Default
pixel_data	np.ndarray	The image data (should be 2D).	required
frame_idx	int	The frame index associated with this data.	0

Returns:

Type	Description
List[TextRegion]	Detected text regions. Also [] when OCR is unavailable, and [] when OCR raised (logged at ERROR), so [] here does not mean "no text". Session.scan_pixel_content() and discover_redaction_zones() check availability first and refuse instead, and report the failures this function only logs.