> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valar.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Attitude Modes

> View, create, edit, and delete attitude modes in your workspace

> For the complete documentation index, see [llms.txt](/llms.txt).

Use this page to manage the attitude mode catalog from the operations dashboard. For an introduction to what an attitude mode is, what body axes mean, and how target types fit together, see [Attitude Modes Overview](/features/attitude/overview).

**Route:** `/attitude/modes`

## Opening the Modes Library

From the attitude modes page header, click **Modes library** to open the workspace catalog. The button sits on the right of the header, alongside **Import** and **Export**. Clicking it opens a wide modal overlay that fills most of your screen.

Inside the overlay, the catalog is rendered as a master-detail editor. The list of modes runs down the left; selecting a mode opens its configuration on the right.

## Viewing the Catalog

The catalog is a single flat list of every attitude mode defined in your workspace, sorted alphabetically by display name. The five pre-installed modes — Earth-pointing, Sun-pointing, Velocity-tracking, Inertial-pointing, and Free drift — appear inline with any modes you have created yourself. Pre-installed modes carry no badge or visual distinction — every mode in the catalog exposes the same Edit, Set as default, and Delete affordances.

The `CUSTOM` placeholder that appears in attitude data imported from [AEM](/file-formats/aem) files is intentionally excluded from this library — those entries live on the [transition schedule](/features/attitude/transitions) instead and can only be added or removed by importing or removing the source `.aem` file.

## Creating a Mode

Click **+ New** at the top of the library list to open the **Create attitude mode** form on the right.

The dropdowns inside the form use the platform's internal target and axis identifiers. Match them to your physical setup using this table:

| What you want the body axis to track                                                        | **Primary Target** dropdown value | Extra parameter                                                                |
| ------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------ |
| **The Sun**                                                                                 | `SUN_DIRECTION`                   | None                                                                           |
| **The Moon, Mars, Jupiter, Saturn, Venus, or Mercury**                                      | `CELESTIAL_BODY`                  | Body picker (`MOON`, `MARS`, `JUPITER`, `SATURN`, `VENUS`, `MERCURY`)          |
| **Earth nadir** — the geodetic point directly below the spacecraft                          | `GEODETIC_NADIR`                  | None                                                                           |
| **A fixed direction on the celestial sphere** — a star, calibration source, or fixed beacon | `FIXED_INERTIAL`                  | Right ascension `0` to `359.999` degrees and declination `-90` to `90` degrees |
| **A ground station** in your workspace                                                      | `GROUND_POINT`                    | Ground-station picker populated from your workspace's ground-station list      |
| **The spacecraft's velocity vector**                                                        | `VELOCITY_VECTOR`                 | None                                                                           |
| **The projection of velocity onto the ground track**                                        | `GROUND_TRACK_VELOCITY`           | None                                                                           |
| **The orbit's angular-momentum vector**                                                     | `ORBIT_ANGULAR_MOMENTUM`          | None                                                                           |

See [Target Types](/features/attitude/overview#target-types) for the conceptual background.

To create a mode:

<Steps>
  <Step title="Enter a Display name">
    Type a name into **Display name**. This is the only required field and is limited to 100 characters; the form blocks submission above that limit.
  </Step>

  <Step title="Add an optional Description">
    Use **Description** to record free-form notes about the mode (intent, mission rationale, references). Limited to 500 characters; leave it blank if you don't need it.
  </Step>

  <Step title="Pick the Primary Target">
    Open the **Primary Target** dropdown and pick the value matching your row in the table above. If the target needs extra parameters — a celestial body, a ground station, or right ascension and declination — the form reveals those inputs below the dropdown.
  </Step>

  <Step title="Pick the Primary Body axis">
    Choose which face of your spacecraft tracks the primary target. The **Primary Body axis** dropdown offers `PLUS_X`, `MINUS_X`, `PLUS_Y`, `MINUS_Y`, `PLUS_Z`, and `MINUS_Z`. See [Body Axes](/features/attitude/overview#body-axes) if you're unsure which face corresponds to each.
  </Step>

  <Step title="Pick the Secondary Target and Secondary Body axis">
    The **Secondary Target** and **Secondary Body axis** controls work the same way and resolve the remaining rotational degree of freedom around the primary direction. The **Secondary Body axis** dropdown disables the axis letter you used for the primary: if your primary is `PLUS_X`, both `PLUS_X` and `MINUS_X` are unavailable for the secondary, so the form forces the two axes onto different physical dimensions.
  </Step>

  <Step title="Save">
    Click **Create**. On success the dialog closes and a confirmation toast appears: "Attitude mode created". The new mode is immediately visible in the library and in every mode picker in your workspace.
  </Step>
</Steps>

## Editing a Mode

Every mode in the catalog is editable, including the five pre-installed modes. Pick a mode in the library list — the right panel becomes the **Edit attitude mode** form, pre-filled with the mode's current values. The fields and validation rules are identical to those described in [Creating a mode](#creating-a-mode).

Click **Update** to save. The dialog closes and a confirmation toast appears: "Attitude mode updated".

<Note>
  Editing a mode applies workspace-wide. Every spacecraft that references the mode — as its default, on a scheduled transition, or anywhere a mode picker uses it — picks up the new configuration on its next attitude calculation. You do not need to touch each spacecraft individually.
</Note>

## Deleting a Mode

Click **Delete** on the mode you want to remove. The confirmation dialog auto-selects one of three branches based on how the mode is currently used in your workspace.

<AccordionGroup>
  <Accordion title="Simple — the mode isn't used anywhere">
    The dialog reads "This mode is not currently used by any spacecraft. This cannot be undone." The footer carries **Cancel** and a destructive **Delete** button.

    Click **Delete** to remove the mode. A confirmation toast appears: "Attitude mode deleted". The mode is removed from the workspace catalog and disappears from every mode picker.
  </Accordion>

  <Accordion title="Rewrite — the mode is scheduled in one or more upcoming transitions">
    When the mode you want to delete is referenced by at least one upcoming scheduled transition, the dialog shows:

    * The affected transition count and spacecraft count, for example "This mode is used in 4 upcoming scheduled transitions across 2 spacecraft."
    * The follow-on statement that deleting will rewrite those transitions: "Deleting it will rewrite those transitions to each spacecraft's current default mode. This cannot be undone."
    * A table listing each affected transition: the spacecraft name, the transition time, and the default mode the transition will rewrite to.
    * A footer with **Cancel** and a destructive **Delete and rewrite transitions** button.

    Confirming the delete removes the mode from the catalog and rewrites every listed transition to the current default mode of its affected spacecraft. The transitions stay on the schedule with their original times — only the target mode changes.
  </Accordion>

  <Accordion title="Inline-blocked — the mode is the default on one or more spacecraft">
    When the mode is configured as the default attitude mode on at least one spacecraft, the delete is blocked. The dialog shows:

    * The inline message: "This mode is set as the default attitude mode on the following spacecraft. Change the default elsewhere before deleting."
    * A list of the spacecraft using this mode as their default.
    * A footer with only a **Close** button — no Delete button is offered.

    Open each affected spacecraft's [transition schedule](/features/attitude/transitions), set a different mode as the default, then return to the library and retry the delete.
  </Accordion>
</AccordionGroup>

## Error States

Three toasts surface when create, edit, or delete cannot complete. In every case the dialog stays open so you can retry without losing your edits.

| Situation                                                                                                            | Toast                                                               | What to do                                                                                                                                                       |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **The mode was deleted by another session** while your dialog was open (404 race).                                   | "This attitude mode no longer exists"                               | Close the dialog — the mode is gone from the catalog already.                                                                                                    |
| **Another session set the mode as a default** after your deletion-impact preview loaded (422 race).                  | "Cannot delete mode — it is the default for one or more spacecraft" | Close the dialog, reopen the library to refresh the impact preview, and either change the default on the affected spacecraft or pick a different mode to delete. |
| **The server fails to save** the create, edit, or delete — HTTP 5xx, network outage, or a generic 422 payload error. | "Failed to save mode — please retry"                                | Your edits remain in the form — click the save button again to retry.                                                                                            |

***

<CardGroup cols={2}>
  <Card title="Attitude modes overview" icon="compass" href="/features/attitude/overview">
    Concepts, body axes, target types, and the unified workspace catalog
  </Card>

  <Card title="Schedule attitude transitions" icon="calendar-days" href="/features/attitude/transitions">
    Plan time-anchored mode switches and override the default
  </Card>

  <Card title="Import and export AEM files" icon="file-export" href="/features/attitude/ephemeris">
    Exchange attitude ephemeris with external partners
  </Card>

  <Card title="Visualize quaternion and Euler angle plots" icon="chart-line" href="/features/attitude/visualization">
    Inspect orientation over time on the operations dashboard
  </Card>
</CardGroup>