# Get-Frame.ps1

Extracts a specific frame of a video file to a PNG image by calling [Get-LastFrame.ps1](Get-LastFrame.md) with an automatically derived output filename. The image path is generated from the `-Video` filename by appending a dash and the resolved frame index zero-padded to at least four digits — for example, `P01.mp4` at frame 10 becomes `P01-0010.png` saved alongside the source video.

## Parameters

- **`-Video`** (required): Path to the input video file. Can be absolute or relative to current directory.
- **`-Frame`** (required): 0-based frame index to extract.
    - Positive values: Direct frame index (e.g., `0` = first frame, `100` = frame 100)
    - Negative values: Count from the end (e.g., `-1` = last frame, `-2` = second-to-last)
    - Values are automatically clamped to the valid range (0 to total frames − 1): a positive value past the last frame gives the last frame, and a negative value before the first frame gives frame 0

## Image Filename Derivation

The output filename is derived from the resolved (always positive) frame index:

| Video | `-Frame` | Total frames | Output image |
| --- | --- | --- | --- |
| `P01.mp4` | `10` | any | `P01-0010.png` |
| `P01.mp4` | `0` | any | `P01-0000.png` |
| `P01.mp4` | `-1` | 300 | `P01-0299.png` |
| `P01.mp4` | `-2` | 300 | `P01-0298.png` |
| `render/shot.mp4` | `42` | any | `render/shot-0042.png` |
| `C:\Videos\take01.mp4` | `100` | any | `C:\Videos\take01-0100.png` |

Negative indices are resolved to the actual frame index before building the filename, so the output always reflects the exact frame that was extracted.

## Output Name Digits

The frame index is padded with zeros to **at least** four digits. Frames `0` to `9999` give exactly four digits (`0010`). Larger numbers are written in full: frame `12345` gives `P01-12345.png`.

## Existing Files

An existing PNG with the same name is **replaced**. The image is written by [Get-LastFrame.ps1](Get-LastFrame.md), which overwrites its output.

## Command Wrapper

`Get-Frame.cmd` takes the video and the frame as **positional** arguments. It calls `Get-Frame.ps1` found on `PATH`, so the script folder must be on `PATH`. Arguments after the frame are passed to `Get-Frame.ps1` unchanged. Only `-WhatIf` and `-Confirm` are accepted there. Other options are rejected.

```cmd
Get-Frame.cmd "P01.mp4" 10
```

This is the same call as `.\Get-Frame.ps1 -Video P01.mp4 -Frame 10`.

## Limitations

- `-Image` is not a parameter of `Get-Frame.ps1`, so it cannot choose the output name. To use a custom name or a numbering pattern, call [Get-LastFrame.ps1](Get-LastFrame.md) with `-Image`:

```powershell
.\Get-LastFrame.ps1 -Video P01.mp4 -Frame 10 -Image "P01-%04d.png"
```

## Examples

**Extract a specific frame:**

```powershell
.\Get-Frame.ps1 -Video P01.mp4 -Frame 10
# Creates: P01-0010.png
```

**Extract the first frame:**

```powershell
.\Get-Frame.ps1 -Video P01.mp4 -Frame 0
# Creates: P01-0000.png
```

**Extract the last frame:**

```powershell
.\Get-Frame.ps1 -Video P01.mp4 -Frame -1
# If video has 300 frames, creates: P01-0299.png
```

**Extract the second-to-last frame:**

```powershell
.\Get-Frame.ps1 -Video P01.mp4 -Frame -2
# If video has 300 frames, creates: P01-0298.png
```

**Extract the 10th frame from the end:**

```powershell
.\Get-Frame.ps1 -Video P01.mp4 -Frame -10
# If video has 300 frames, creates: P01-0290.png
```

**Using absolute paths:**

```powershell
.\Get-Frame.ps1 -Video "C:\Videos\P01.mp4" -Frame 50
# Creates: C:\Videos\P01-0050.png
```

## Safe Execution

This script supports `-WhatIf` and `-Confirm` for safe execution (forwarded to `Get-LastFrame.ps1`):

- **`-WhatIf`**: Simulate the operation without extracting the frame. Shows what would be done.
- **`-Confirm`**: Prompt for confirmation before extracting the frame.

**Simulate without extracting:**

```powershell
.\Get-Frame.ps1 -Video P01.mp4 -Frame 10 -WhatIf
```

**Prompt before extraction:**

```powershell
.\Get-Frame.ps1 -Video P01.mp4 -Frame 10 -Confirm
```