LuluSplat turns photos and video into 3D Gaussian Splats, on this computer's GPU.

CHOOSING A TOOL

Building something new, from photos or video:
  lulusplat_run - extracts frames, solves the cameras, trains. Minutes to hours.
  Ordinary video, 360 equirectangular video and Insta360 dual-fisheye (.insv)
  are recognised automatically.

You already have a COLMAP reconstruction solved elsewhere:
  lulusplat_import - wraps it in a NEW project and trains. Skips solving.
  Pass the folder holding BOTH images/ and the sparse model, not the
  sparse/0 folder itself.

A LuluSplat project already exists and you want to train it again - more
iterations, or changed settings:
  lulusplat_train - trains IN PLACE. Reuses the frames and the camera solve,
  copies nothing. This is almost always what "run it again" means.
  resume=true carries on from the checkpoint the last run left
  (output/checkpoint.lulu) instead of starting over; iterations must then be
  above the step it reached.
  Do NOT use lulusplat_run for this: it would redo frame extraction and
  camera solving, which can take an hour and cannot improve on work already
  done.

WHERE THINGS GO

`out` is a PARENT folder. A project folder named after the capture is
created inside it. Given out=D:\Splats and a capture called bicycle, the
project is D:\Splats\bicycle_lulusplat (a number is added if that exists).

Never guess that path - every tool returns the real one as `project`. Use
that value verbatim for later calls.

RUNS TAKE MINUTES

Building tools return a job id straight away. They do not wait.
  1. call the tool, keep `job` from the reply
  2. poll lulusplat_job_status - it reports stage, iteration and splat count
  3. when state is no longer "running", call lulusplat_job_result

Poll every few seconds, not continuously. Tell the user what stage it is in
rather than going quiet.

ONE AT A TIME. A second build is refused while one runs, naming the job to
poll. That is not an error to retry - wait for the first to finish.

Jobs live only as long as the server. If it restarts, the job id is gone,
but the project on disk is unharmed - inspect it with lulusplat_project_info.

BEFORE YOU GUESS, LOOK

Do not speculate about what a folder contains.
  lulusplat_list_projects - what has been built under a folder
  lulusplat_project_info - frames, registered images, splat count, quality,
                           output paths and checkpoint for one project

Training logs (training.log) are exposed as resources. Asked why a run was
slow or poor, read the log rather than guessing: it records duration, the
settings used, held-out quality, and every earlier run of the same project.

SETTINGS WORTH KNOWING

iterations - default 7000. More is slower and usually sharper; 15000-30000
is a reasonable range for a final result. Diminishing past that.

max_dimension - longest edge of each extracted frame. Lower it if the GPU is
short of memory.

technique - "vanilla" (default) or "mcmc". vanilla grows splats where detail
is missing (the original 3DGS recipe). mcmc moves a fixed budget of splats
instead of growing them, and is usually sharper for the same training time
with predictable memory. Its budget follows iterations: 100k splats up to
15000, rising to 500k by 30000. Changing technique on an existing project is
a lulusplat_train, not a new build (and a checkpoint only continues with the
technique that wrote it).

For 360 or drone footage, ask lulusplat_capture_advice with aerial=true
before advising on a shoot.

WHAT NOT TO DO

Do not re-run a full build to change training settings - use lulusplat_train.
Do not invent project paths - read them from a tool result.
Do not start a second build while one is running.
Do not claim a run finished until job_status says so.
