---

name: visualization-and-serving description: "Guides the historical SECOND KITTI web viewer, its Flask API, browser configuration, visualization payloads, and guarded checkpoint inference routes." disable-model-invocation: true metadata: disco-role: operating license: MIT

Visualization and serving

Use this route for requests such as start the KITTI viewer web backend, serve the browser UI, load point clouds or detections, configure Flask/CORS, buildNet, run viewer inference, or use the PyQt viewer. The supported route here is the old repository's web KITTI lidar viewer; the desktop Qt viewer is historical and deprecated.

Safety and support boundary

• This is a source-distilled protocol, not a replacement server. A server is started only when the user explicitly asks for it, with user-owned paths and ports. No server, browser, GUI, dataset, or detector execution is part of skill verification.

• The checkout has no setup metadata. Do not assume pip install -e . works. First run the safe dependency probe:

  python sub-skills/visualization-and-serving/scripts/check_viewer_deps.py --json
  

  Missing components are reported without launching Flask. --help is also safe. A passing import probe does not prove detector compatibility.

• The historical model path uses legacy spconv/Numba APIs. Current spconv 2.x is not proven compatible: in the inspected environment the legacy spconv.utils.VoxelGeneratorV2 and non_max_suppression symbols are absent. Do not claim that buildNet or inference works, even if CUDA and PyTorch import successfully. Route compatibility and checkpoints to training-and-inference.

• The backend binds to 127.0.0.1 and enables permissive Flask-CORS. CORS does not make a loopback server remotely reachable, and the API has no authentication. Keep it local or use an explicitly user-controlled secure tunnel; never expose arbitrary host paths or a public service by default.

Web workflow

1. Prepare a local KITTI-style dataset and generated info pickle. Use data-preparation for layout and info validation; the browser sends filesystem paths to the backend host, not to the browser machine.

2. In a caller-managed environment where the second package and web dependencies are importable, start the backend only on request:

   python -m second.kittiviewer.backend.main main --port=<BACKEND_PORT>
   

   The source default is 16666; the command is a long-running foreground service. Stop it with the terminal's normal interrupt. A safe import/help diagnostic is:

   python -m second.kittiviewer.backend.main --help
   

   If import fails before help, stop and use troubleshooting; do not silently substitute modern detector APIs.

3. Serve the supplied web frontend assets separately, from the directory that contains index.html, without exposing a broad parent directory:

   python -m http.server <FRONTEND_PORT> --directory <frontend-assets-directory>
   

   The README's example uses port 8000. Open http://127.0.0.1:<FRONTEND_PORT>/ in a browser and set the UI's backend field to http://127.0.0.1:<BACKEND_PORT> (the UI adds http:// when a scheme is omitted). Verify browser developer tools show POSTs to the same backend origin and no CORS error.

4. Set datasetClassName to the registered class, normally KittiDataset, and set rootPath and infoPath to paths readable by the backend. Click load. Expect status: normal and an image_indexes list. Enter an index shown by that list in the bottom control and press Enter; previous/next only works after a successful load.

5. Optionally set detPath and click loadDet. The backend accepts either a pickled detection result file or a directory in the historical KITTI label format. Treat this as best-effort legacy state: the current endpoint stores dt_annos, but the point-cloud response does not consistently merge those annotations into its payload. Check the actual response before relying on drawDet.

6. For checkpoint inference, first complete load, then set checkpointPath and configPath, click buildNet, and only then click inference. This route is guarded and unverified for modern spconv; use training-and-inference for checkpoint/config compatibility and api-reference for exact request fields.

Routes and handoffs

• Read web-viewer.md for the browser/backend state sequence, payload encodings, and visualization behavior.
• Read api-reference.md before constructing a direct HTTP request or diagnosing a response shape.
• Read troubleshooting.md for missing imports, CORS/URL mismatches, invalid info or detection inputs, API ordering errors, and legacy checkpoint failures.
• Route dataset directories, info generation, and dataset class registration to data-preparation. Route box coordinate conventions and evaluation-format conversion to geometry-and-evaluation.

Explicit non-goals

Do not copy, wrap, or launch the deprecated viewer.py, glwidget.py, or control_panel.py desktop application. Those Qt/OpenGL modules require a separate GUI stack and are retained only as deprecation evidence. Prefer the web lidar path, and recommend a maintained successor such as OpenPCDet or MMDetection3D for new work.