# Standard mosaic rotation

The Projects sky preview renders from the viewer's current centre immediately,
including before coordinates have been typed or the sky has been moved.
The yellow reference camera frame remains visible during mosaic editing.

Every mosaic exposure carries these preferences through project saves, copies,
imports and calendar payloads:

| Field | Default | Meaning |
| --- | --- | --- |
| `mosaic_square_by_camera_rotation` | `true` | Align the pointing grid with the measured camera axes. |
| `mosaic_custom_rotation_enabled` | `false` | Override camera alignment with an absolute grid angle. |
| `mosaic_custom_rotation_deg` | `0` | Custom angle in degrees, using the same convention as `image_rotation`. |

Negative angles and multiple turns are accepted. Custom rotation takes priority
when both checkboxes are selected. Turning both off selects a zero-degree RA/Dec
grid. These settings rotate the grid and its requested outline; camera frames
retain their measured orientation. They do not command a hardware rotator.
SmartStack FOV remains a preview of the RA/Dec-aligned crop inside each frame.

The blue rectangle is fitted inside the union of the displayed panel footprints.
It excludes uncovered gaps, holes and concave cutouts; it does not use the convex
outer envelope. Its size and orientation are numerically estimated, so it may be
smaller than the mathematical maximum. Disconnected panels can yield a rectangle
within just one connected portion. This coverage diagnostic does not block a
requested grid. Pointing counts are determined by the overlap planner below.

Width and height retain their existing meanings before grid rotation: width is
an RA coordinate span, height a Dec span. Convert width to an on-sky angle at
the declination in the requested interval closest to the equator. Panel counts
and overlap use these dimensions. The planner uses grid-aligned coverage cells
inside the full camera frames. Adjacent cells overlap by the requested fraction
along each grid axis and their union covers the requested rectangle. Camera/grid
angle differences reduce the usable cell dimensions and can require extra rows
or columns. Every cell is checked against its projected spherical camera frame;
counts refine as needed for changes in the local meridian and projection. This
calculation neither crops the acquired detector frame nor changes the requested
overlap. RA wrap and pole crossings use spherical projection. Panel order and
progress indices remain column-major.

CodexOBS implements the matching transformation in `mosaic_grid.py` and applies
it at each slew using the current mosaic centre, including cycle dithers and
recentering. The plan is calculated after centering and cycle dither. If the
camera has no measured rotation, OBS uses its existing centering exposure to
measure it. A missing angle after that is reported as a planning failure:
overlap cannot be calculated without the camera's orientation, even when the
grid uses a custom angle or zero-degree RA/Dec alignment.