DatasetViewer Search Results Visualization

Important

Purpose: This guide is for Developers and Engineers who run CAD similarity search with CADSearch and want to visualize the returned hits.

For dataset exploration workflows (querying file IDs and viewing pre-generated previews), start with Data Visualization Experience.

Overview

DatasetViewer can visualize similarity search results returned by CADSearch.

Instead of requiring pre-generated PNG previews, show_search_results() generates preview images on-the-fly from the CAD file paths stored in each search hit.

Use this when you have:

  • A list of hits from CADSearch.search_by_shape(...) (or similar)

  • CAD files accessible at the paths in each hit

Prerequisites

  • A working HOOPS AI installation and valid license

  • A list of search hits (objects with at least .id and .score)

  • The CAD files referenced by hit.id must be readable from the current machine

Quick Start

from hoops_ai.insights import DatasetViewer

# 1) Run a CAD similarity search (any approach that returns hits with .id/.score)
# See :doc:`embeddings-retrieval` for end-to-end retrieval examples.
hits = ...  # for example: CADSearch.search_by_shape("query.step", top_k=10)

# 2) Visualize results
viewer = DatasetViewer(file_ids=[], png_paths=[], scs_paths=[])
viewer.show_search_results(hits)

# In scripts (non-notebook), you may need:
# import matplotlib.pyplot as plt
# plt.show()

What show_search_results() does

At a high level, show_search_results():

  1. Reads the CAD file path from each hit (hit.id)

  2. Generates PNG preview images into an output folder

  3. Displays the results in a grid

  4. Optionally adds labels (scores and/or filenames)

  5. Optionally saves the figure to an image file

Common Patterns

Scores only (hide filenames)

viewer = DatasetViewer(file_ids=[], png_paths=[], scs_paths=[])
viewer.show_search_results(
    hits,
    show_filenames=False,
    show_scores=True,
)

Limit and format a large result set

viewer = DatasetViewer(file_ids=[], png_paths=[], scs_paths=[])
viewer.show_search_results(
    hits,
    k=25,
    grid_cols=5,
    figsize=(20, 20),
    title="Top 25 Similar Parts",
)

Save the figure to disk

viewer = DatasetViewer(file_ids=[], png_paths=[], scs_paths=[])
viewer.show_search_results(
    hits,
    save_path="results/search_output.png",
)

Control where generated PNGs go

viewer = DatasetViewer(file_ids=[], png_paths=[], scs_paths=[])
viewer.show_search_results(
    hits,
    output_dir="results/pngs",
    overwrite=False,
)

Parameter Reference

Comparison with other DatasetViewer methods

Troubleshooting

No search hits provided

If hits is empty, nothing can be visualized. Check that your search call returned results.

Note: when hits is empty, show_search_results(...) returns None.

Gray placeholders instead of images

Placeholders typically indicate the CAD file could not be loaded or a PNG could not be generated.

Common causes:

  1. The path stored in hit.id does not exist on this machine

  2. The CAD file format cannot be loaded

  3. The file is corrupted

Performance notes

Generating previews requires loading CAD files and exporting images, which can take time for large result sets. Use k to limit how many hits are displayed.

Resource cleanup

DatasetViewer initializes a process pool for parallel preview generation. When you are done with a viewer, call close() to release resources.

viewer = DatasetViewer(file_ids=[], png_paths=[], scs_paths=[])
viewer.show_search_results(hits)
viewer.close()

Or use a context manager:

with DatasetViewer(file_ids=[], png_paths=[], scs_paths=[]) as viewer:
viewer.show_search_results(hits)