########################################## DatasetViewer Search Results Visualization ########################################## .. sidebar:: Table of Contents .. contents:: :local: :depth: 1 .. important:: **Purpose**: This guide is for **Developers and Engineers** who run CAD similarity search with :class:`CADSearch ` and want to **visualize the returned hits**. For dataset exploration workflows (querying file IDs and viewing pre-generated previews), start with :doc:`cad-data-visualization`. Overview ======== :class:`DatasetViewer ` can visualize similarity search results returned by :class:`CADSearch `. Instead of requiring pre-generated PNG previews, :meth:`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 =========== .. code-block:: python 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, :meth:`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) ---------------------------- .. code-block:: python 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 ----------------------------------- .. code-block:: python 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 ----------------------- .. code-block:: python viewer = DatasetViewer(file_ids=[], png_paths=[], scs_paths=[]) viewer.show_search_results( hits, save_path="results/search_output.png", ) Control where generated PNGs go ------------------------------- .. code-block:: python viewer = DatasetViewer(file_ids=[], png_paths=[], scs_paths=[]) viewer.show_search_results( hits, output_dir="results/pngs", overwrite=False, ) Parameter Reference =================== .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Parameter - Type - Default - Description * - ``hits`` - list - Required - Search hits returned by CADSearch (each hit must expose ``.id`` and ``.score``) * - ``output_dir`` - str | Path - Auto - Where generated PNG previews are written. If not provided, uses the viewer reference directory when available, otherwise ``./out``. * - ``k`` - int - None - Maximum number of hits to display (None = show all) * - ``grid_cols`` - int - 4 - Number of columns in the results grid * - ``figsize`` - tuple - Auto - Matplotlib figure size ``(width, height)`` * - ``show_scores`` - bool - True - Show similarity scores in the per-item labels * - ``show_filenames`` - bool - True - Show filenames in the per-item labels * - ``title`` - str - "CAD Similarity Search Results" - Figure title * - ``missing_color`` - tuple - (200, 200, 200) - RGB color for placeholder tiles when a preview cannot be generated * - ``save_path`` - str | Path - None - Save the figure to this file path * - ``is_white_background`` - bool - True - Use a white background when exporting PNG previews * - ``overwrite`` - bool - True - Overwrite existing generated PNG previews in ``output_dir`` Comparison with other DatasetViewer methods =========================================== .. list-table:: :header-rows: 1 :widths: 30 20 50 * - Method - Input - Use case * - :meth:`show_preview_as_image()` - File IDs - Dataset exploration using pre-generated PNG previews * - :meth:`show_search_results()` - Search hits - Similarity search visualization with on-the-fly PNG generation * - :meth:`show_preview_as_3d()` - File IDs - Interactive 3D viewing of dataset items 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 :meth:`close()` to release resources. .. code-block:: python viewer = DatasetViewer(file_ids=[], png_paths=[], scs_paths=[]) viewer.show_search_results(hits) viewer.close() Or use a context manager: .. code-block:: python with DatasetViewer(file_ids=[], png_paths=[], scs_paths=[]) as viewer: viewer.show_search_results(hits) Related Guides ============== - :doc:`embeddings-retrieval` - :doc:`cad-data-visualization`