# Usage

ViewStretch has one job: stretch what you see in the 3D Viewport along the current view axes, non-destructively, and let you reset it instantly. There are two ways to trigger it — the viewport button and the keyboard shortcuts — and it behaves differently in Object Mode and Edit Mode.

## The viewport button

A small button sits below the navigation icons in the top-right corner of the 3D Viewport.

- **Hold and drag** — stretch. Dragging horizontally scales along the view's X axis, dragging vertically scales along the view's Y axis.
- **Release** — the stretch stays active. The button turns **blue** to remind you a stretch rig is live in the scene.
- **Click without dragging** — reset. Everything returns to its original state and the hidden rig is removed.

## Keyboard shortcuts (Object Mode)

- `Ctrl + Alt + LMB` drag — stretch. Release to keep it; click without dragging to reset.
- `Ctrl + Alt + RMB` — reset.
- Hold `Shift` while dragging — precision mode (finer control of the scale factor).
- `RMB` or `Esc` during a drag — cancel the current gesture.

While you drag, the viewport header shows the live scale factors so you always know exactly how much you have stretched.

## Object Mode

In Object Mode, ViewStretch stretches **everything visible** in the viewport.

```{image} ./_static/images/viewstretch_object_before.png
:alt: A car model at its original proportions in Object Mode
:width: 100%
```

Hold and drag to stretch. Here the model has been scaled down along the view's X axis:

```{image} ./_static/images/viewstretch_object_after.png
:alt: The same model stretched along the view X axis in Object Mode
:width: 100%
```

Because the stretch is aligned to the view, orbiting to a different angle and stretching again rescales along that new view. The effect is always relative to what you currently see:

```{image} ./_static/images/viewstretch_object_before_rear.png
:alt: The model seen from a three-quarter rear view before stretching
:width: 100%
```

```{image} ./_static/images/viewstretch_object_after_rear.png
:alt: The same three-quarter rear view after stretching along the view axis
:width: 100%
```

Under the hood, ViewStretch walks each visible object up to the root of its hierarchy and parents that root to the hidden Empty, so rigs and nested chains follow as one piece without breaking any parenting. Linked (library) objects are skipped. By default only geometry-like objects are affected; enable **Include All Object Types** in the preferences to also stretch cameras, lights, and similar objects.

## Edit Mode

In Edit Mode (Mesh, Curve, Curves, or Surface), ViewStretch stretches **only the object(s) you are editing** — and only through the **viewport button**. The keyboard shortcuts intentionally pass through in Edit Mode so routine editing gestures (like edge-ring selection with Ctrl+Alt) are never stolen.

```{image} ./_static/images/viewstretch_edit_before.png
:alt: A single body panel being edited, at its original proportions
:width: 100%
```

Using the viewport button, only the edited panel is stretched while the rest of the model stays untouched:

```{image} ./_static/images/viewstretch_edit_after.png
:alt: Only the edited panel is stretched, the rest of the model is unchanged
:width: 100%
```

The original parenting of the edited object is saved and fully restored when you reset.

## Resetting

A reset restores every original transform and parent relationship exactly, then deletes the hidden Empty. You can reset in any of these ways:

- Click the viewport button without dragging.
- Click (without dragging) during a `Ctrl+Alt+LMB` gesture.
- Press `Ctrl+Alt+RMB` in Object Mode.

If several stretch rigs are active at once (for example an Object-Mode stretch plus an Edit-Mode stretch), a single reset dismantles them all in the correct order.