hoops_ai.insights
Quick Overview
Modules
Visualization utilities for HOOPS AI Insights.
Classes
CADViewer([host, port, static_folder, ...])High-level CAD viewer with HOOPS AI integration.
DatasetViewer(file_ids, png_paths, scs_paths)Powerful visualization tool for exploring CAD datasets.
Functions
quick_view(filepath[, display_mode, ...])Quick one-liner to view a CAD file.
Data Analysis and Visualization Module
The Insights module provides comprehensive data analysis and visualization capabilities for CAD datasets, machine learning results, and geometric data. It bridges the gap between complex CAD data processing and intuitive visual understanding, offering both interactive exploration tools and automated analysis workflows.
This module enables researchers, engineers, and data scientists to gain deep insights into CAD data patterns, model performance, geometric relationships, and dataset characteristics through rich visualizations and statistical analysis.
For visualization techniques and analysis workflows, see the CAD Data Visualization Programming Guide.
This module provides high-level visualization and interactive exploration capabilities for CAD models in Jupyter notebooks.
The insights module wraps the hoops-viewer package and integrates seamlessly with HOOPS AI’s Flow architecture, DataStorage, and ML pipelines.
Examples:
# Quick visualization:
from hoops_ai.insights import quick_view
viewer = quick_view("model.step")
# Advanced usage:
from hoops_ai.insights import CADViewer
with CADViewer(display_mode='sidecar') as viewer:
viewer.load_cad_file("model.step")
viewer.show()
viewer.set_face_color([0, 1, 2], [255, 0, 0])
- class hoops_ai.insights.CADViewer(host='127.0.0.1', port=None, static_folder=None, display_mode='sidecar', auto_display=False, silent=True)
Bases:
objectHigh-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.
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()
- Parameters:
- 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:
Click on a face in the 3D view to highlight it
Use Ctrl+Click to highlight multiple faces
Call this method to retrieve the selection
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.
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}")
- load_cad_file(filepath, auto_convert=True, white_background=True)
Load a CAD file for viewing.
- Parameters:
- Returns:
True if loading was successful, False otherwise
- Return type:
- load_scs_file(filepath)
Load an SCS file directly (no conversion needed).
- set_face_color(face_indices, color=None)
Set color for specific faces.
- Parameters:
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:
- Returns:
True if color is valid (3 integers, 0-255), False otherwise
- Return type:
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)
- class hoops_ai.insights.DatasetViewer(file_ids, png_paths, scs_paths, file_names=None)
Bases:
objectPowerful visualization tool for exploring CAD datasets.
This class accepts lists of file IDs and their corresponding visualization paths to enable visualization of CAD files as either:
Image collages/grids using PNG previews
Interactive 3D views using stream cache files
The DatasetViewer is designed to work with data from DatasetExplorer but remains decoupled, accepting only the necessary lists for maximum flexibility.
Examples:
# Get data from explorer explorer = DatasetExplorer(flow_output_file="flow.json") cache_df = explorer.get_stream_cache_paths() # Extract lists file_ids = cache_df['id'].tolist() png_paths = cache_df['stream_cache_png'].tolist() scs_paths = cache_df['stream_cache_3d'].tolist() file_names = cache_df['name'].tolist() # Create viewer viewer = DatasetViewer(file_ids, png_paths, scs_paths, file_names) # Or use convenience method viewer = DatasetViewer.from_explorer(explorer) # Query files and visualize query_ids = explorer.get_file_list(group="graph", where=lambda ds: ds['num_nodes'] > 30) viewer.show_preview_as_image(query_ids, k=25)
- Parameters:
- filter_by_availability(file_ids, require_png=False, require_3d=False)
Filter file IDs based on visualization data availability.
This is useful to ensure you only try to visualize files that have the necessary visualization data available.
- Parameters:
- Returns:
Filtered list of file IDs
- Return type:
Examples:
# Get files that have PNG previews files_with_images = viewer.filter_by_availability( all_file_ids, require_png=True ) # Get files that have both PNG and 3D fully_visualizable = viewer.filter_by_availability( all_file_ids, require_png=True, require_3d=True )
- classmethod from_explorer(explorer)
Convenience constructor to create DatasetViewer from a DatasetExplorer.
This method queries the explorer for stream cache paths and creates a DatasetViewer with the extracted data.
- Parameters:
explorer (DatasetExplorer) – DatasetExplorer instance
- Returns:
DatasetViewer instance
- Return type:
Examples:
explorer = DatasetExplorer(flow_output_file="flow.json") viewer = DatasetViewer.from_explorer(explorer) viewer.print_statistics()
- get_available_file_ids()
Get list of all file IDs that have visualization data available.
- Examples::
available_ids = viewer.get_available_file_ids() print(f”Files with visualization: {len(available_ids)}”)
- get_file_info(file_id)
Get visualization information for a specific file ID.
- Parameters:
file_id (int) – File ID to query (int or convertible to int)
- Returns:
Dictionary with ‘name’, ‘png_path’, ‘stream_cache_path’ or None if not found
- Return type:
Examples:
info = viewer.get_file_info(42) print(f"File name: {info['name']}") print(f"PNG available: {info['png_path'] is not None}")
- get_statistics()
Get statistics about available visualization data.
- Returns:
Dictionary containing statistics about the dataset visualization data
- Return type:
Examples:
stats = viewer.get_statistics() print(f"Total files: {stats['total_files']}") print(f"PNG available: {stats['files_with_png']}") print(f"3D cache available: {stats['files_with_3d']}") print(f"Coverage: {stats['coverage_percentage']:.1f}%")
- print_statistics()
Print formatted statistics about visualization data availability.
Examples
>>> viewer.print_statistics()
>>> Dataset Visualization Statistics ... ═══════════════════════════════════════════════ ... Total files: 234 ... Files with PNG preview: 234 (100.0%) ... Files with 3D cache: 234 (100.0%) ... Overall coverage: 100.0%
- Return type:
None
- refresh_mapping(file_ids, png_paths, scs_paths, file_names=None)
Refresh the internal file mapping with new data.
Use this method if the dataset has been updated or you want to update the visualization paths.
- Parameters:
- Return type:
None
Examples:
# Update with new data viewer.refresh_mapping(new_ids, new_pngs, new_scs, new_names) print(f"Refreshed mapping contains {len(viewer._file_mapping)} files")
- show_preview_as_3d(file_ids, k=5, display_mode='inline', layout='sequential', host='127.0.0.1', start_port=8000, silent=True, width=400, height=400)
Open interactive 3D viewers for file IDs using stream cache files.
This method creates CADViewer instances for each file, loading their 3D stream cache representations. Users can interact with the 3D models directly in the notebook.
- Parameters:
file_ids (List[int]) – List of file IDs to visualize (ints, numpy array, or convertible to int)
k (int) – Maximum number of 3D viewers to open (default: 5)
display_mode (str) – Display mode - ‘inline’, ‘sidecar’, or ‘none’ (default: ‘inline’)
layout (str) – Layout strategy - ‘sequential’ or ‘grid’ (default: ‘sequential’) Note: ‘grid’ not yet implemented, uses sequential
host (str) – Host address for viewer servers (default: ‘127.0.0.1’)
start_port (int) – Starting port for viewer servers (default: 8000)
silent (bool) – Whether to suppress viewer server output (default: True)
width (int) – Width of inline viewer in pixels (default: 400)
height (int) – Height of inline viewer in pixels (default: 400)
- Returns:
List of CADViewer instances (one per displayed file)
- Return type:
Examples:
# Open 3 compact inline 3D viewers (forms a grid-like layout) viewers = viewer.show_preview_as_3d(file_ids, k=3) # Open larger inline viewers viewers = viewer.show_preview_as_3d( file_ids, k=3, width=600, height=500 ) # Open viewers in sidecar layout (full size) viewers = viewer.show_preview_as_3d( file_ids, k=5, display_mode='sidecar' ) # Interact with specific viewer selected_faces = viewers[0].get_selected_faces() viewers[0].set_face_color(selected_faces, [255, 0, 0]) # Clean up viewers when done for v in viewers: v.terminate()
- show_preview_as_image(file_ids, k=25, grid_cols=6, figsize=(15, 5), show_labels=True, label_format='id', title=None, missing_color=(200, 200, 200), save_path=None)
Generate an image grid visualization from file IDs.
This method creates a matplotlib figure displaying PNG previews of CAD files in a grid layout. It’s perfect for quickly visualizing query results.
- Parameters:
file_ids (List[int]) – List of file IDs to visualize (ints, numpy array, or convertible to int)
k (int) – Maximum number of files to display (default: 25)
grid_cols (int | None) – Number of columns in grid. If None, auto-calculated (default: None)
figsize (Tuple[int, int] | None) – Figure size as (width, height). If None, auto-calculated (default: None)
show_labels (bool) – Whether to show file labels on images (default: True)
label_format (str) – Label format - ‘id’, ‘name’, or ‘both’ (default: ‘id’)
title (str | None) – Overall figure title (default: None)
missing_color (Tuple[int, int, int]) – RGB color for files without PNG preview (default: gray)
save_path (str | None) – If provided, save the figure to this path (default: None)
- Returns:
matplotlib Figure object
- Return type:
matplotlib.pyplot.Figure
Examples:
# Simple grid visualization fig = viewer.show_preview_as_image(file_ids, k=16) # Custom 4-column grid with names fig = viewer.show_preview_as_image( file_ids, k=20, grid_cols=4, label_format='name', title='High Complexity Parts' ) # Save to file fig = viewer.show_preview_as_image( file_ids, k=100, save_path='results/query_visualization.png' )
- hoops_ai.insights.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:
- Returns:
CADViewer instance
- Return type:
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)
