📝 Add docstrings to codex/implement-param-driven-3d-viewer

Docstrings generation was requested by @shayancoin.

* #456 (comment)

The following files were modified:

* `backend/api/routes_catalog.py`
* `backend/tests/test_routes_catalog.py`
* `frontend/src/app/components/Viewer3D.tsx`
* `frontend/src/app/configurator/page.tsx`
* `scripts/generate_reference_glbs.py`

Author: coderabbitai[bot]

backend/api/routes_catalog.py

@@ -28,6 +28,19 @@
 
 @lru_cache(maxsize=1)
 def _load_catalog(path: Path) -> Any:
+    """
+    Load and parse a JSON catalog file from the given filesystem path.
+    
+    Parameters:
+        path (Path): Filesystem path to the catalog JSON file.
+    
+    Returns:
+        Any: The parsed JSON content (typically a dict or list).
+    
+    Raises:
+        HTTPException: With status 500 and detail "catalog file not found" if the file is missing.
+        HTTPException: With status 500 and detail "catalog file is invalid" if the file contains invalid JSON.
+    """
     try:
         with path.open("r", encoding="utf-8") as fh:
             return json.load(fh)
@@ -39,6 +52,19 @@ def _load_catalog(path: Path) -> Any:
 
 @lru_cache(maxsize=1)
 def _load_mesh_manifest(path: Path) -> Dict[str, Any]:
+    """
+    Load and parse the mesh manifest JSON from the given filesystem path.
+    
+    Parameters:
+        path (Path): Filesystem path to the mesh manifest JSON file.
+    
+    Returns:
+        manifest (Dict[str, Any]): Parsed manifest JSON as a dictionary.
+    
+    Raises:
+        HTTPException: 500 with detail "mesh manifest not found" if the file is missing;
+                       500 with detail "mesh manifest is invalid" if the file contains invalid JSON.
+    """
     try:
         with path.open("r", encoding="utf-8") as fh:
             return json.load(fh)
@@ -49,6 +75,20 @@ def _load_mesh_manifest(path: Path) -> Dict[str, Any]:
 
 
 def _find_manifest_entry(manifest: Dict[str, Any], variant_id: str) -> Dict[str, Any]:
+    """
+    Find the manifest entry that corresponds to the given variant identifier.
+    
+    Parameters:
+        manifest (Dict[str, Any]): Parsed mesh manifest containing a "models" list.
+        variant_id (str): Variant identifier to locate. Can be an entry's `id`, a `variant`, or a composite of the form `"variant@lodX"`.
+    
+    Returns:
+        Dict[str, Any]: The matching model entry from the manifest.
+    
+    Raises:
+        HTTPException: 500 if the manifest is missing or malformed (no "models" list or invalid model entries).
+        HTTPException: 404 if no matching model entry is found.
+    """
     models = manifest.get("models")
     if not isinstance(models, list):
         raise HTTPException(status_code=500, detail="mesh manifest missing models")
@@ -89,6 +129,18 @@ def _find_manifest_entry(manifest: Dict[str, Any], variant_id: str) -> Dict[str,
 
 
 def _decode_mesh_bytes(entry: Dict[str, Any]) -> bytes:
+    """
+    Decode base64-encoded GLB mesh data from a manifest entry.
+    
+    Parameters:
+        entry (Dict[str, Any]): Manifest entry expected to contain a non-empty `meshBase64` string.
+    
+    Returns:
+        bytes: The decoded GLB binary data.
+    
+    Raises:
+        HTTPException: 500 if `meshBase64` is missing or empty, or if the base64 data is invalid.
+    """
     mesh_value = entry.get("meshBase64")
     if not isinstance(mesh_value, str) or not mesh_value:
         raise HTTPException(status_code=500, detail="mesh manifest missing mesh data")
@@ -100,6 +152,17 @@ def _decode_mesh_bytes(entry: Dict[str, Any]) -> bytes:
 
 
 def _parse_glb_document(data: bytes) -> Dict[str, Any]:
+    """
+    Extracts and parses the JSON chunk from a GLB binary.
+    
+    Returns:
+        document (Dict[str, Any]): The parsed JSON object from the GLB's JSON chunk.
+    
+    Raises:
+        HTTPException: If the GLB header is invalid (500, "invalid GLB header").
+        HTTPException: If the JSON chunk cannot be parsed (500, "invalid GLB metadata").
+        HTTPException: If no JSON chunk is present in the GLB (500, "GLB missing JSON chunk").
+    """
     if len(data) < 12 or data[:4] != b"glTF":
         raise HTTPException(status_code=500, detail="invalid GLB header")
 
@@ -120,6 +183,18 @@ def _parse_glb_document(data: bytes) -> Dict[str, Any]:
 
 
 def _extract_variant_extras(document: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Locate and return a node's extras dictionary that contains the "paform:variant" key from a parsed GLB JSON document.
+    
+    Parameters:
+        document (Dict[str, Any]): Parsed GLB JSON document (typically the JSON chunk).
+    
+    Returns:
+        Dict[str, Any]: The node's `extras` dictionary that includes the `"paform:variant"` entry.
+    
+    Raises:
+        HTTPException: With status 500 if no node extras containing `"paform:variant"` are found.
+    """
     nodes = document.get("nodes")
     if isinstance(nodes, list):
         for node in nodes:
@@ -133,14 +208,32 @@ def _extract_variant_extras(document: Dict[str, Any]) -> Dict[str, Any]:
 
 @router.get("/option-graph")
 def get_option_graph() -> Any:
-    """Return the option graph catalog used by CPQ pricing flows."""
+    """
+    Retrieve the option graph catalog used by CPQ pricing flows.
+    
+    Returns:
+        catalog (Any): The parsed catalog data (typically a dict or list) representing the option graph.
+    """
 
     return _load_catalog(CATALOG_PATH)
 
 
 @router_mesh.get("/{variant_id}/mesh")
 def get_catalog_mesh(variant_id: str) -> Dict[str, Any]:
-    """Return the GLB payload and variant metadata for the requested catalog entry."""
+    """
+    Return the GLB payload and extracted variant metadata for the specified catalog entry.
+    
+    Returns:
+        payload (Dict[str, Any]): Dictionary with keys:
+            - id (str | None): manifest entry id.
+            - variant (str): variant code or resolved variant identifier.
+            - lod (int | None): level-of-detail value from the manifest entry.
+            - sha256 (str | None): SHA-256 checksum from the manifest entry.
+            - bytes (int): size in bytes (from entry or inferred from decoded data).
+            - mesh (str | None): Base64-encoded GLB data from the manifest entry.
+            - metadata (Dict[str, Any]): `paform:variant` metadata extracted from the GLB.
+            - extras (Dict[str, Any]): extras object from the GLB node that contained `paform:variant`.
+    """
 
     manifest = _load_mesh_manifest(MESH_MANIFEST_PATH)
     entry = _find_manifest_entry(manifest, variant_id)
@@ -168,7 +261,13 @@ def get_catalog_mesh(variant_id: str) -> Dict[str, Any]:
 
 @router_mesh.get("/{variant_id}/mesh.glb")
 def download_catalog_mesh(variant_id: str) -> Response:
-    """Return the raw GLB binary for the requested catalog entry."""
+    """
+    Serve the raw GLB binary for a catalog variant as a downloadable file.
+    
+    Returns:
+        Response: HTTP response with the GLB bytes as media type `model/gltf-binary` and a
+        `Content-Disposition` header prompting download using `<id|variant|variant_id>.glb` as the filename.
+    """
 
     manifest = _load_mesh_manifest(MESH_MANIFEST_PATH)
     entry = _find_manifest_entry(manifest, variant_id)
@@ -177,4 +276,4 @@ def download_catalog_mesh(variant_id: str) -> Response:
     filename = f"{(entry.get('id') or entry.get('variant') or variant_id)}.glb"
     headers = {"Content-Disposition": f"attachment; filename=\"{filename}\""}
 
-    return Response(content=data, media_type="model/gltf-binary", headers=headers)
+    return Response(content=data, media_type="model/gltf-binary", headers=headers)

backend/tests/test_routes_catalog.py

@@ -42,7 +42,12 @@ def test_get_catalog_mesh_glb_downloads_binary() -> None:
 
 
 def test_get_catalog_mesh_missing_variant_returns_404() -> None:
+    """
+    Check that requesting a nonexistent catalog mesh variant returns HTTP 404.
+    
+    Sends a GET request for a missing catalog variant and asserts the response status code is 404.
+    """
     client = TestClient(app)
 
     response = client.get("/api/catalog/unknown_variant/mesh")
-    assert response.status_code == 404
+    assert response.status_code == 404

frontend/src/app/components/Viewer3D.tsx

@@ -64,6 +64,16 @@ const isObject3DLike = (
   return isVector3Like(candidate.scale) && isVector3Like(candidate.position);
 };
 
+/**
+ * Marks a mesh source as having its LOD0 become visible shortly after it is mounted or changed.
+ *
+ * When `src` is provided in a browser environment, schedules a two-frame animation-frame delay, then
+ * records the current timestamp in a global Map at `window.__lod0VisibleAt` keyed by `src` and
+ * dispatches a `CustomEvent` named `"lod0:visible"` with `{ src, ts }` in `event.detail`. Cancels
+ * any pending animation frames when `src` changes or the component unmounts. No-op on the server.
+ *
+ * @param src - A string identifier or URL for the mesh whose LOD0 visibility should be recorded; if `null` nothing is scheduled
+ */
 function useLodVisibility(src: string | null) {
   useEffect(() => {
     if (typeof window === 'undefined' || !src) {
@@ -104,6 +114,15 @@ function useLodVisibility(src: string | null) {
   }, [src]);
 }
 
+/**
+ * Selects the primary manifest entry for a given variant id following priority rules.
+ *
+ * Searches the provided manifest for an entry whose `id` exactly matches `variantId`, then for an entry whose `variant` equals `variantId` and has `lod` undefined or `0`. If no exact or zero-LOD match is found, returns the first entry whose `variant` equals `variantId` (used as a fallback).
+ *
+ * @param manifest - Array of manifest entries to search
+ * @param variantId - Variant identifier to select the primary entry for
+ * @returns The chosen manifest entry for `variantId`, or `undefined` if none found
+ */
 function selectPrimaryEntry(manifest: MeshManifestItem[], variantId: string): MeshManifestItem | undefined {
   let fallback: MeshManifestItem | undefined;
   for (const entry of manifest) {
@@ -125,6 +144,15 @@ function selectPrimaryEntry(manifest: MeshManifestItem[], variantId: string): Me
   return fallback;
 }
 
+/**
+ * Create a blob object URL from a base64-encoded GLB payload for use with model loaders.
+ *
+ * When `meshBase64` is provided, the hook decodes it into a binary GLB Blob and returns a corresponding object URL.
+ * The created object URL is revoked automatically when `meshBase64` changes or the component unmounts.
+ *
+ * @param meshBase64 - A base64-encoded GLB (binary glTF) payload; pass `null`/`undefined` to clear the URL.
+ * @returns The object URL for the decoded GLB Blob, or `null` if no payload was provided or decoding failed.
+ */
 function useMeshObjectUrl(meshBase64: string | null | undefined): string | null {
   const [objectUrl, setObjectUrl] = useState<string | null>(null);
 
@@ -170,6 +198,19 @@ type LoadedModelProps = {
   onWidthChange: (widthMm: number) => void;
 };
 
+/**
+ * Render a loaded GLTF scene with scale transform controls and report width updates.
+ *
+ * Applies the provided transform to the scene, exposes interactive scaling along the configured axis,
+ * disables camera orbiting while the user is manipulating the model, and invokes `onWidthChange`
+ * when the effective model width (in millimeters) changes due to a scale operation.
+ *
+ * @param modelUrl - Object URL or path to a GLTF/GLB model to load and render
+ * @param meshId - Identifier used for LOD visibility tracking for the loaded model
+ * @param transform - Optional transform state (scale, translation, axis, base dimensions) to apply to the model; defaults are used when omitted
+ * @param onWidthChange - Callback invoked with the computed width in millimeters when the model's scale along the active axis changes
+ * @returns The React element that renders the loaded model with TransformControls
+ */
 function LoadedModel({ modelUrl, meshId, transform, onWidthChange }: LoadedModelProps) {
   const gltf = useGLTF(modelUrl);
   const orbitControls = useThree((state) => state.controls) as { enabled?: boolean } | null;
@@ -234,6 +275,13 @@ function LoadedModel({ modelUrl, meshId, transform, onWidthChange }: LoadedModel
   );
 }
 
+/**
+ * Render a simple placeholder box mesh used when a real model is unavailable.
+ *
+ * The component marks a placeholder key as visible for LOD tracking and returns a compact box mesh with a blue standard material.
+ *
+ * @returns A React element containing the fallback box mesh
+ */
 function FallbackModel() {
   useLodVisibility('mock-model');
 
@@ -245,6 +293,18 @@ function FallbackModel() {
   );
 }
 
+/**
+ * Render a 3D viewer that loads and displays a GLTF model for the specified variant.
+ *
+ * The component selects a primary manifest entry for `variantId`, ensures the mesh
+ * manifest is loaded, decodes a base64 GLTF payload to an object URL when available,
+ * and renders either the loaded model with transform controls or a simple fallback.
+ * It also exposes the current mesh width in the DOM for testing and updates persisted
+ * transform width via the configurator store when the model is scaled.
+ *
+ * @param variantId - The variant identifier used to select the manifest entry and transform key
+ * @returns A React element containing the Three.js Canvas, model or fallback, environment (optional), and controls
+ */
 export default function Viewer3D({ variantId }: Viewer3DProps) {
   const disableEnvironment = process.env.NEXT_PUBLIC_DISABLE_ENVIRONMENT === 'true';
   const disableModelLoading = process.env.NEXT_PUBLIC_DISABLE_MODEL_LOADING === 'true';
@@ -303,4 +363,4 @@ export default function Viewer3D({ variantId }: Viewer3DProps) {
       )}
     </>
   );
-}
+}

frontend/src/app/configurator/page.tsx

@@ -2,6 +2,13 @@ import { Box, Flex } from '@chakra-ui/react'
 import Viewer3D from '../components/Viewer3D'
 import ConfiguratorPanel from '../components/configurator-panel'
 
+/**
+ * Renders the product configurator page with a responsive layout containing a 3D viewer and a configuration panel.
+ *
+ * The 3D viewer is passed the variant id `'base_600'`.
+ *
+ * @returns The React element representing the configurator page layout.
+ */
 export default function ConfiguratorPage() {
   const demoVariant = 'base_600'
   return (
@@ -16,4 +23,3 @@ export default function ConfiguratorPage() {
   )
 }
 
-