hoops_ai.insights.viewer

Main viewer module for HOOPS AI Insights.

This module provides the CADViewer class for high-level CAD visualization.

Functions

quick_view(filepath[, display_mode, ...])

Quick one-liner to view a CAD file.

Classes

CADViewer([host, port, static_folder, ...])

High-level CAD viewer with HOOPS AI integration.

class hoops_ai.insights.viewer.CADViewer(host='127.0.0.1', port=None, static_folder=None, display_mode='sidecar', auto_display=False, silent=True)

Bases: object

High-level CAD viewer with HOOPS AI integration.

This class provides a simple interface for viewing CAD models in Jupyter notebooks with automatic resource management and display handling.

Parameters:

host (str) – Host address for viewer server (default: ‘127.0.0.1’)
port (int | None) – Port for viewer server. If None (default), automatically finds a free port starting from 8000. If specified, uses that exact port (will fail if port is busy).
static_folder (Path | None) – Path to static folder for serving files
display_mode (str) – Display mode (‘sidecar’, ‘inline’, ‘none’)
auto_display (bool) – Whether to automatically display on load
silent (bool) – Whether to suppress server output

Examples

>>> # Basic usage:
>>> viewer = CADViewer()
>>> viewer.load_cad_file("model.step")
>>> viewer.show()
>>>
>>> # With context manager:
>>> with CADViewer() as viewer:
>>>     viewer.load_cad_file("model.step")
>>>     viewer.show()
>>>
>>> # Sidecar display:
>>> viewer = CADViewer(display_mode='sidecar')
>>> viewer.load_cad_file("model.step")
>>> viewer.show()

clear_face_colors()

Clear all face colors.

Removes all color highlighting from faces, returning them to default appearance.

color_faces_by_groups(face_groups, delay=0.3, clear_first=True, verbose=True)

Color faces by groups with progress feedback.

This method colors multiple groups of faces, where each group has a list of face indices, an RGB color, and a description.

Parameters:

face_groups (List[Tuple[List[int], Tuple[int, int, int], str]]) – List of (face_indices, color, description) tuples where color is (R, G, B) tuple with 0-255 values
delay (float) – Seconds to pause between coloring different groups (visual effect)
clear_first (bool) – Whether to clear existing colors before applying new ones
verbose (bool) – Whether to print progress with colored terminal indicators

Examples

>>> groups = [
...     ([1, 2, 6], (255, 0, 0), 'through hole'),
...     ([3, 5], (0, 0, 255), 'blind hole')
... ]
>>> viewer.color_faces_by_groups(groups, delay=0.5)
🟥 through hole (3 faces)
🟦 blind hole (2 faces)

get_selected_faces()

Get face indices selected by user in the viewer.

User should: 1. Click on a face in the 3D view to highlight it 2. Use Ctrl+Click to highlight multiple faces 3. Call this method to retrieve the selection

Returns:: List of selected face indices
Return type:: List[int]

Examples

>>> selected = viewer.get_selected_faces()
>>> print(f"Selected {len(selected)} faces: {selected}")
>>> viewer.set_face_color(selected, [0, 255, 0])  # Color them green

get_status()

Get comprehensive viewer status information.

Returns:: Dictionary containing viewer state information
Return type:: Dict[str, Any]

Examples

>>> status = viewer.get_status()
>>> print(f"Active: {status['active']}")
>>> print(f"Model loaded: {status['model_loaded']}")

get_viewer_url()

Get the viewer server URL.

Returns:: Viewer URL if active, None otherwise
Return type:: str | None

Examples

>>> url = viewer.get_viewer_url()
>>> print(f"Viewer running at: {url}")

property is_active: bool: Check if viewer is active and running.

property is_model_loaded: bool: Check if a model is currently loaded in the viewer.

load_cad_file(filepath, auto_convert=True, white_background=True)

Load a CAD file for viewing.

Parameters:

filepath (str) – Path to the CAD file
auto_convert (bool) – Whether to automatically convert CAD to SCS format (default: True)
white_background (bool) – Whether to use white background for conversion (default: True)

Returns:

True if loading was successful, False otherwise

Return type:

bool

load_scs_file(filepath)

Load an SCS file directly (no conversion needed).

Parameters:: filepath (str) – Path to the SCS file
Returns:: True if loading was successful, False otherwise
Return type:: bool

set_face_color(face_indices, color=None)

Set color for specific faces.

Parameters:

face_indices (List[int]) – List of face indices to color
color (List[int] | None) – RGB color as [r, g, b] (0-255). If None, uses default highlight.

Examples

>>> viewer.set_face_color([0, 1, 2])  # Default color
>>> viewer.set_face_color([0, 1, 2], [255, 0, 0])  # Red

show(display_mode=None, **display_kwargs)

Display the viewer in Jupyter.

Parameters:

display_mode (str | None) – Display mode (‘sidecar’, ‘inline’, ‘none’). If None, uses instance default.
**display_kwargs – Additional arguments for display functions

Returns:

DisplayHandle or None

Return type:

DisplayHandle | None

terminate()

Terminate the viewer and clean up resources.

This method should be called when done with the viewer to properly shut down the server and release resources.

static validate_color(color)

Validate RGB color values.

Parameters:: color (List[int]) – RGB color as [r, g, b]
Returns:: True if color is valid (3 integers, 0-255), False otherwise
Return type:: bool

Examples

>>> CADViewer.validate_color([255, 0, 0])  # True
>>> CADViewer.validate_color([255, 0, 256])  # False (out of range)
>>> CADViewer.validate_color([255, 0])  # False (wrong length)

hoops_ai.insights.viewer.quick_view(filepath, display_mode='sidecar', static_folder=None, **kwargs)

Quick one-liner to view a CAD file.

This convenience function creates a viewer, loads the file, and displays it in a single call. By default, automatically finds a free port.

Parameters:

filepath (str) – Path to the CAD file
display_mode (str) – Display mode (‘sidecar’, ‘inline’)
static_folder (Path | None) – Optional static folder path
**kwargs – Additional arguments for CADViewer (e.g., port=9000 for specific port)

Returns:

CADViewer instance

Return type:

CADViewer

Examples

>>> # Auto-find port (default)
>>> viewer = quick_view("model.step")

>>> # Inline display with auto port
>>> viewer = quick_view("model.step", display_mode='inline')

>>> # Specify exact port (strict mode)
>>> viewer = quick_view("model.step", port=9000)

hoops_ai.insights.viewer

Hello! I'm HOOPSY