Visualization¶

Visualization contracts and task-aware orchestration.

class pathforge.core.visualization.base.TaskVisualizationAdapterBase[source]¶

Bases: ABC

Base class for task-specific visualization adapters.

task_name: str = ''¶

__init__(experiment: Experiment) → None[source]¶

Parameters:: experiment (Experiment)
Return type:: None

abstractmethod discover_runs() → list[VisualizationRunContext][source]¶

Discover all visualizable runs for the configured task.

Return type:: list[VisualizationRunContext]

abstractmethod render_run(run_context: VisualizationRunContext, *, requested_visualizations: list[str], subset_ids: set[str] | None) → list[Path][source]¶

Render the requested visualizations for one discovered run.

Parameters:

run_context (VisualizationRunContext)
requested_visualizations (list[str])
subset_ids (set[str] | None)

Return type:

list[Path]

class pathforge.core.visualization.types.VisualizationRunContext[source]¶

Bases: object

Visualization context for one discovered run.

Inputs: - task_name: registered task name. - run_dir: absolute path to the discovered run directory. - combo_cfg: benchmark combination used for run discovery. - manifest: parsed run manifest payload. - aggregation_level: aggregation level used by the task outputs.

task_name: str¶

run_dir: Path¶

combo_cfg: ComboConfig¶

manifest: dict[str, Any]¶

aggregation_level: str¶

__init__(task_name: str, run_dir: Path, combo_cfg: ComboConfig, manifest: dict[str, Any], aggregation_level: str) → None¶

Parameters:

task_name (str)
run_dir (Path)
combo_cfg (ComboConfig)
manifest (dict[str, Any])
aggregation_level (str)

Return type:

None

class pathforge.core.visualization.types.VisualizationSummary[source]¶

Bases: object

Summary of one config-driven visualization execution.

Inputs: - task_name: task visualized. - run_dirs: run directories that were processed. - created_files: absolute PNG paths written to disk.

task_name: str¶

run_dirs: list[str]¶

created_files: list[str]¶

__init__(task_name: str, run_dirs: list[str] = <factory>, created_files: list[str] = <factory>) → None¶

Parameters:

task_name (str)
run_dirs (list[str])
created_files (list[str])

Return type:

None

pathforge.core.visualization.registry.task_visualization_adapter(task_name: str) → Callable[[type['TaskVisualizationAdapterBase']], type['TaskVisualizationAdapterBase']][source]¶

Parameters:: task_name (str)
Return type:: Callable[[type[‘TaskVisualizationAdapterBase’]], type[‘TaskVisualizationAdapterBase’]]

pathforge.core.visualization.registry.build_task_visualization_adapter(name: str, experiment: Experiment) → TaskVisualizationAdapterBase[source]¶

Instantiate one registered task visualization adapter.

Parameters:

name (str)
experiment (Experiment)

Return type:

TaskVisualizationAdapterBase

pathforge.core.visualization.registry.import_task_visualization_adapter_modules(package_name: str = 'pathforge.core.visualization.tasks') → None[source]¶

Import all task-visualization adapter modules so registration side effects run.

Parameters:: package_name (str)
Return type:: None

class pathforge.core.visualization.orchestrator.VisualizationOrchestrator[source]¶

Bases: object

Run config-driven visualization for the configured task.

__init__(experiment: Experiment) → None[source]¶

Parameters:: experiment (Experiment)
Return type:: None

visualize() → dict[str, Any][source]¶

Render all configured visualizations for all discovered task runs.

Return type:: dict[str, Any]

pathforge.core.visualization.thumbnail.render_thumbnail_image(*, thumbnail_image: Any, jpeg_quality: int = 65, max_long_side: int | None = 1200) → bytes[source]¶

Render one full-slide thumbnail image as JPEG bytes.

Inputs: - thumbnail_image: PIL image or numpy array thumbnail. - jpeg_quality: JPEG quality used for encoded bytes. - max_long_side: optional resize cap applied before encoding.

Returns: - bytes: encoded JPEG image.

Parameters:

thumbnail_image (Any)
jpeg_quality (int)
max_long_side (int | None)

Return type:

bytes

pathforge.core.visualization.thumbnail.decode_thumbnail_image(image_bytes: bytes) → Image[source]¶

Decode one stored thumbnail byte payload into a PIL RGB image.

Parameters:: image_bytes (bytes)
Return type:: Image

pathforge.core.visualization.thumbnail.fit_image_to_canvas(image: Image, *, canvas_size: tuple[int, int], background_rgb: tuple[int, int, int] = (255, 255, 255)) → Image[source]¶

Contain one image inside a fixed-size canvas while preserving aspect ratio.

Parameters:

image (Image)
canvas_size (tuple[int, int])
background_rgb (tuple[int, int, int])

Return type:

Image

pathforge.core.visualization.thumbnail.crop_thumbnail_background(image: Image, *, threshold: int = 245, padding: int = 6) → Image[source]¶

Crop near-white background from one thumbnail image.

Returns the input image unchanged when no foreground bbox can be detected.

Parameters:

image (Image)
threshold (int)
padding (int)

Return type:

Image

pathforge.core.visualization.thumbnail.project_level0_to_thumbnail(*, x_level0: float, y_level0: float, downscale_x: float, downscale_y: float) → tuple[float, float][source]¶

Project one level-0 point into thumbnail pixel space.

Returns: - (x_thumb, y_thumb): thumbnail-space coordinates.

Parameters:

x_level0 (float)
y_level0 (float)
downscale_x (float)
downscale_y (float)

Return type:

tuple[float, float]

pathforge.core.visualization.thumbnail.crop_thumbnail_to_tissue_bounds(image: Image, *, tissue_polygons: Sequence[Sequence[Sequence[Sequence[float]]]] | None, downscale_x: float, downscale_y: float, border_px: int = 12) → Image[source]¶

Crop one thumbnail to the tight tissue bounding box plus a small border.

Returns the original image when no valid tissue polygons are available.

Parameters:

image (Image)
tissue_polygons (Sequence[Sequence[Sequence[Sequence[float]]]] | None)
downscale_x (float)
downscale_y (float)
border_px (int)

Return type:

Image

class pathforge.core.visualization.tasks.slide_retrieval.SlideRetrievalVisualizationAdapter[source]¶

Bases: TaskVisualizationAdapterBase

Config-driven visualization adapter for slide retrieval runs.

This adapter discovers completed slide-retrieval runs from benchmark combinations, then delegates actual rendering to the slide-retrieval visualization service.

task_name: str = 'slide_retrieval'¶

classmethod get_discovery_keys() → list[str][source]¶

Return type:: list[str]

discover_runs() → list[VisualizationRunContext][source]¶

Discover all visualizable runs for the configured task.

Return type:: list[VisualizationRunContext]

render_run(run_context: VisualizationRunContext, *, requested_visualizations: list[str], subset_ids: set[str] | None) → list[Path][source]¶

Render the requested visualizations for one discovered run.

Parameters:

run_context (VisualizationRunContext)
requested_visualizations (list[str])
subset_ids (set[str] | None)

Return type:

list[Path]