# Cubemap, batch, and autograd

| Field | Contract |
| --- | --- |
| **Application** | Project and reconstruct panoramic views |
| **Input** | ERP arrays or NCHW tensors |
| **Output** | Cubemap/gnomonic batches and reconstructed ERP |
| **Strategy** | Projection-domain |
| **API** | Cubemap APIs and `EquirectangularImage.process_views` |
| **Stability** | Stable geometry; Compatibility containers |
| **Dependencies** | Core; Torch optional for tensor examples |
| **Evidence** | Executed analytic fixtures |

## How this application is composed

Cubemap and gnomonic projectors come from `panorai.geometry`; batch and dtype
preservation belong to the selected NumPy/Torch backend; reconstruction uses
explicit support masks. `process_views()` wraps those stages when one callback
and one fused ERP are sufficient. The lower-level objects remain available for
custom batching, autograd or per-face outputs.

See the {ref}`capability-map-cubemap-batch` section of the spherical
computer-vision guide for what PanorAi projects, when an ERP is reconstructed,
and why neither cubemap conversion nor batched projection is a spherical
convolution.

**PanorAi-specific:** fixed cubemap face order/orientation, canonical ray
sampling, batch-preserving projection, explicit support and inverse ERP
reconstruction. The operation or model applied to each face remains caller-
owned.

## Cubemap round trip

Cubemap faces use the immutable order `front`, `right`, `back`, `left`, `up`,
`down`. This continuous RGB example uses bilinear interpolation and reconstructs
an `HWC` panorama.

```{literalinclude} ../../../scripts/run_documentation_examples.py
:language: python
:dedent: 4
:start-after: DOCS_CUBEMAP_START = None
:end-before: DOCS_CUBEMAP_END = None
```

## Torch batch and input gradients

Torch is optional. Batched image tensors use `NCHW`; the result preserves
batch, channels, dtype, and device. Autograd is supported for input values, not
for geometric parameters.

```{literalinclude} ../../../scripts/run_documentation_examples.py
:language: python
:dedent: 8
:start-after: DOCS_TORCH_START = None
:end-before: DOCS_TORCH_END = None
```

Execute every example, including Torch, with:

```console
python scripts/run_documentation_examples.py --source-checkout --torch
```