# User Interface

## First Look
Here' what GAC looks like when first opened (minus the red overlay):

```{figure} /_static/img/user-interface/overview_at_startup2_detailed.png
:alt: overview at startup
:name: overview-at-startup
:width: 100%
:align: center
```

The interface is made of:
1. a top menu for project management, screenshots, and setting some options
2. a top toolbar with quick access to most useful tools to edit a model
3. shortcut links our socials, itch.io, discourse, bluesky - to give us feedback about your experience and get help
4. the vertical menu -- _vmenu_ -- to quicly show/hide tools
5. a left & right panels with main editing tools -- described [below](#tools)
6. the 3D scene - see [there](#moving-around-the-scene)
7. a status bar for high level information

(tools)=
## Tools
Tools are:
- the [resource explorer](#ResourceExplorer)
- the [inspector](#Inspector)
- the [painter](#Painter)
- the [actions log](#ActionsLog)
- the [exporter](#Exporter)
- the settings -- self-explanatory

(moving-around-the-scene)=
## Moving Around The Scene
The scene is where your creation takes shape. Drag & drop resources from the [resource explorer](#ResourceExplorer) onto the scene, and use your mouse to move around:
- `left click + drag` to pan the camera
- `right click + drag` to rotate the camera
- `mouse wheel up/down` to zoom in/out
- `shift + mouse wheel up/down` to raise/lower the camera

## Selection
A model can be selected by clicking on it. `Shift+click` adds/remove a model from the selection. `Wheel click + drag` allows for multiple selection at once.


## Top Toolbar
use tools from the top toolbar to put them into position:

```{figure} /_static/img/user-interface/top-toolbar.detailed.png
:alt: sticker tool
:name: sticker-tool
:width: 100%
:align: center
```

1. mouse dragging modes [⤵](#mouse-dragging-modes)
2. gizmo transformations toggler [⤵](#gizmo-transformations-toggler)
3. local/global changes toggle [⤵](#local-global-changes-toggle)
4. grid snapping [⤵](#grid-snapping)
5. vertex snapping tool [⤵](#vertex-snapping-tool)

(mouse-dragging-modes)=
### Mouse Dragging Modes
`Ignore Underlying Surface` drags the selection on a horizontal plane centered on the selection.
```{figure} /_static/img/user-interface/drag_align.none.gif
:alt: vanilla drag align
:name: drag-align-vanilla
:width: 60%
:align: center
```

`Conserve Angle` drags the selection along the surface under the mouse, and does not affect the rotation of selected models. centered on the selection.
```{figure} /_static/img/user-interface/drag_align.conserve_angle.gif
:alt: drag align conserve angle
:name: drag-align-conserve-angle
:width: 60%
:align: center
```

`Align to surface` drags the selection along the surface under the mouse, and rotate the selection along the surface normal. centered on the selection.
```{figure} /_static/img/user-interface/drag_align.hard_align.gif
:alt: drag align hard
:name: drag-align-hard
:width: 60%
:align: center
```

`Smooth Align` drags the selection along the surface under the mouse, and rotate the selection along the surface normal, accounting for neighbor surfaces' normals, so that the rotation is smooth. centered on the selection.
```{figure} /_static/img/user-interface/drag_align.smooth_align.gif
:alt: drag align smooth
:name: drag-align-smooth
:width: 60%
:align: center
```

(gizmo-transformations-toggler)=
### Gizmo Transformations Toggler
Those button show/hide translation/rotation/scale handles from the gizmo under the current selection.

(local-global-changes-toggle)=
### Local/Global Changes Toggle
Changes are made in the global scope by default, where `x/y/z` axis are absolute for all models, no matter their current transformation. When local mode is enabled, transformation and rotation handles are aligned to the selection's transform. This makes it easier to precisely place objets sometimes.

(grid-snapping)=
### Grid Snapping
Grid snapping for translation (with gizmo handles) moves the selection by increments of `n` units, where `n` is set in the first text area after the button, `0.25` by default.

Grid snapping for rotation (with gizmo handles) rotates the selection by increments of `n` units, where `n` is set in the first text area after the button, `15°` by default.

Grid snapping for scale (with gizmo handles) scales the selection by increments of `n` units, where `n` is set in the first text area after the button, `0.1` by default. Scale is relative to the size of the model, before a transformation is applied, so it's never an absolute value.

(vertex-snapping-tool)=
### Vertex Snapping Tool
Vertex snapping lets you _precisely_ move a model so that the selected vertex of this model (_source vertex_) is at the exact same location as the selected vertex of another model (_target vertex_):
```{figure} /_static/img/user-interface/vertex_snapping_tool.gif
:alt: vertex snapping
:name: vertex-snapping
:width: 60%
:align: center
```

::::{note}
Vertices are always moved from source to target. Please mind the order in which you select them!
::::