CLI Package
===========

The CLI package provides command-line tools for serving and inspecting Luxar datasets.

.. seealso::

   This page documents the Python CLI **modules** (autodoc). For the
   authoritative catalog of user-facing ``luxar ...`` commands and the workflow
   guides that cover them, see the :doc:`/guides/user/CLI_REFERENCE`.

.. automodule:: luxar.cli
   :members:
   :undoc-members:
   :show-inheritance:

Main Application
----------------

The main application provides the ``luxar`` command-line interface with commands for
serving data and inspecting datasets. (There is no separate viewer-build command —
the bundled viewer is served automatically when you serve data with ``--viewer``.)

.. automodule:: luxar.cli.main
   :no-members:

Key Functions
~~~~~~~~~~~~~

.. autofunction:: luxar.cli.main.create_server_app

   This function is particularly useful for:

   * **Integration Testing**: Create test servers that serve real Zarr data
   * **Programmatic Server Creation**: Embed Luxar server in larger applications
   * **Custom Deployments**: Configure and run servers with custom settings

   Example usage in tests::

      from luxar.cli.main import create_server_app
      import uvicorn

      # Create server app
      app = create_server_app("/path/to/data.luxar.zarr")

      # Run with uvicorn
      uvicorn.run(app, host="127.0.0.1", port=8000)

Serving
-------

The server application factory and CORS/serving helpers. ``create_server_app``
is re-exported from ``luxar.cli.main`` (used above) but its real home is
``luxar.cli.serving``.

.. automodule:: luxar.cli.serving
   :members:
   :undoc-members:

Utilities
---------

Utility functions for port management, viewer building, and dataset inspection.

.. automodule:: luxar.cli.utils
   :members:
   :undoc-members:

Network Simulation
------------------

Network simulation middleware for testing viewer performance under various network conditions.

.. automodule:: luxar.cli.network_simulation
   :members:
   :undoc-members:

Network Profiles
~~~~~~~~~~~~~~~~

The network simulation supports several built-in profiles that simulate real-world network conditions:

* **3g**: Mobile 3G connection (384 kbps, 300ms latency, 1% packet loss)
* **4g**: Mobile 4G/LTE (10 Mbps, 100ms latency, 0.5% packet loss)
* **5g**: 5G mobile (100 Mbps, 30ms latency, 0.1% packet loss)
* **satellite**: Satellite internet (25 Mbps, 600ms latency, 1% packet loss)
* **rural**: Rural DSL (1 Mbps, 100ms latency, 2% packet loss)
* **congested**: Congested network (2 Mbps, 200ms latency, 3% packet loss)
* **slow-broadband**: Slow broadband (5 Mbps, 50ms latency, 0.5% packet loss)
* **broadband**: Home broadband (50 Mbps, 20ms latency, 0.1% packet loss)
* **fast-broadband**: Fast broadband (200 Mbps, 10ms latency, 0.05% packet loss)

Example usage::

   # Simulate 3G connection
   luxar serve data.luxar.zarr --profile 3g --viewer

   # Custom slow connection
   luxar serve data.luxar.zarr --bandwidth 500kbps --latency 200ms --packet-loss 2%

   # Override profile settings
   luxar serve data.luxar.zarr --profile 4g --latency 300ms

See the :doc:`../guides/developer/NETWORK_SIMULATION_SPEC` for detailed specifications.

Export
------

Export Luxar scenes as standalone offline viewer bundles.

.. automodule:: luxar.cli.export
   :members:
   :undoc-members:

Native Bundles
--------------

Producers for double-clickable native bundles wrapped around the Go-compiled
launcher binary (``packages/luxar-launcher``). Used internally by the
``luxar export --native`` subcommand to emit ``.app`` bundles on macOS and
portable folders on Linux. The bundle layout, ``Info.plist`` generator, and
launcher-binary lookup all live in this module.

.. automodule:: luxar.cli.native_app
   :members:
   :undoc-members:

Mesh Commands
-------------

Registration surface for the ``luxar mesh import`` and ``luxar mesh lod``
commands.

.. automodule:: luxar.cli.mesh_commands
   :members:
   :undoc-members:

Mesh Operations
~~~~~~~~~~~~~~~

Implementations behind ``luxar mesh ...``. Each module registers one command
family on the shared Typer application.

.. automodule:: luxar.cli.mesh_ops
   :members:
   :undoc-members:

GSplat Commands
---------------

CLI commands for fitting, converting, rendering, merging, and managing Gaussian splats.

.. automodule:: luxar.cli.gsplat_commands
   :members:
   :undoc-members:

GSplat Configuration
~~~~~~~~~~~~~~~~~~~~

Configuration loading and validation for GSplat CLI commands.

.. automodule:: luxar.cli.gsplat_config
   :members:
   :undoc-members:

GSplat Operations
~~~~~~~~~~~~~~~~~

Implementations behind ``luxar gsplat ...``: fitting/calibration (``fitting/``),
whole-timelapse batch fitting (``batch/``), post-fit editing and inspection
(``transforms/`` plus the ``scene``/``inspect``/``interchange`` root modules).
The package ``__init__`` is docstring-only — the Typer groups are assembled in
``luxar.cli.gsplat_commands``, and each family's registration surface is its own
``commands.py``.

.. automodule:: luxar.cli.gsplat_ops
   :members:
   :undoc-members:

LOD Command
~~~~~~~~~~~

Implementation of the ``luxar gsplat lod`` command (recipe-driven LOD topology
construction).

.. automodule:: luxar.cli.lod
   :members:
   :undoc-members:

Info Command
------------

Implementation of the ``luxar info`` dataset-inspection command.

.. automodule:: luxar.cli.info_command
   :members:
   :undoc-members:

Optimize Command
----------------

Implementation of the ``luxar optimize`` re-chunking command — a thin Typer
layer over :mod:`luxar.io.optimize`, which owns every decision about what a
re-chunk may change and what it must not.

.. automodule:: luxar.cli.optimize_command
   :members:
   :undoc-members: