# User Interface

{{ project_name }} is a desktop UI for viewing meshes generated by your Python
scripts. This guide is organized around common tasks and the controls that help
you complete them.

![User Interface](images/startup_window.png)

## Load, Reload, Export

- If you want to load a mesh script, use `File > Load .py...` or the `Load .py...`
  button to pick a Python file that defines `create_mesh`.
- If you want to re-run the last script after edits, use `File > Reload` or the
  `Reload` button.
- If you want to export the current mesh, use `File > Export...` or the `Export`
  button. Export is enabled only after a load completes.
- If an export format reports a missing dependency, install the package named
  in the error, or choose a different format.

## View and Inspect

- If you want to refit the camera to the mesh, use `View > Frame` or the `Frame`
  button.
- If you want fixed viewpoints, use `XYZ`, `X`, `Y`, or `Z` (also in the `View`
  menu). `XYZ` moves to a canonical view; `X`, `Y`, and `Z` show the mesh from
  the positive axes.
- If you want perspective or orthographic projection, use the radio buttons
  labeled `Perspective` and `Orthogonal` (also in the `View` menu).
- If you want visual helpers, toggle `Grid`, `Axes`, `Edges`, or `Gnomon` from
  the right-side panel or the `View` menu. The grid is a size reference with
  minor lines at 0.1 and larger lines at 1 and 10.

### Grid

  ![Grid Example](images/grid.png)
  
### Edges
  
  ![Edges Example](images/edges.png)

## Navigate the Viewport

- If you want to orbit, left-click and drag in the viewport.
- If you want to zoom/dolly, use the mouse wheel.
- If you want keyboard navigation, use `W/S` or `Up Arrow/Down Arrow` for forward/back, 
  `A/D` or `Left Arrow/Right Arrow` for left/right, 
  and `Q/E` for up/down.

## Fonts Helper

- If you want to browse system fonts for text-based meshes, use `Help > Fonts`.
  You can filter by name and copy a `Font Name:style=Style` string to the
  clipboard for your scripts.

  ![Fonts Helper](images/fonts.png)

## Status Feedback

- If you want to see loading progress, watch the right-side progress bar. It
  pulses while loading and fills when complete.
- The viewport background color also provides status:
    - Blue: currently loading
    - Green: loaded successfully
    - Yellow: loaded successfully in debug mode (`create_mesh` returned or yielded an array of meshes).
    - Red: the script has an error.

## Reference Appendix

### View Directions

- `XYZ` moves to a canonical view: +X points right and toward the screen, +Y
  points right and away, +Z points up.
- `X` shows the mesh from the +X side, `Y` from +Y, and `Z` from +Z.

### Export Dependencies

- Some export formats require extra packages. Errors tell you what to install,
  such as `pycollada` for `dae` or `networkx` for `3mf`.
