# gizlang/capture

a captured place (3D Gaussians of a real place, made from a video) as a game streams it. The place is cut into square tiles of CELL meters on integer cells (the open world's own). Each tile has levels of detail: level 0 all its splats with their colors of degree 1, each next level about a quarter as many, merged by their moments and of degree 0. A level is drawn out to its REACH from the eye; past the last, the tile is not drawn. A tile's COLLIDER is one triangle mesh (glTF) that physics and navigation take, as they take a set's.

```gizlang
import * as Capture from "gizlang/capture";
```

## Types

### `Tile`

```gizlang
type Tile = { x: i64; z: i64; levels: Vec<string>; collider?: string; }
```

A tile at cell X, Z (its square from X * cell to (X + 1) * cell meters, and likewise in z): the PLY file of each of
its LEVELS, nearest first, and its COLLIDER's glTF file.

- `x`: `i64`
- `z`: `i64`
- `levels`: `Vec<string>`
- `collider`: `_gizlang_sdk_core.Option<string>`

### `Capture`

```gizlang
type Capture = { cell: f64; reach: Vec<f64>; tiles: Vec<Tile>; }
```

A captured place: its tiles of CELL meters, and the REACH of each level (meters from the eye to a tile's middle,
level 0's first).

- `cell`: `f64`
- `reach`: `Vec<f64>`
- `tiles`: `Vec<gizlang_capture.Tile>`

### `Stand`

```gizlang
type Stand = { turn: Rotation; first: Point3; eye: f64; }
```

How a place made from a video stands in a game: the turn from the video's frame, its first eye (which stands over
the origin) and that eye's height over the ground.

- `turn`: `gizlang_geometry.Rotation`
- `first`: `gizlang_geometry.Point3`
- `eye`: `f64`

### `Leveled`

```gizlang
type Leveled = { splats: Gaussians; eye: f64; }
```

A place as a game stands in it, and the height of its first eye above the ground (Leveled.eye).

- `splats`: `gizlang_meshdraw.Gaussians`
- `eye`: `f64`

### `Cut`

```gizlang
type Cut = { x: i64; z: i64; levels: Vec<Gaussians>; }
```

A tile as it is made, before its files are written: its cell and the splats of each level.

- `x`: `i64`
- `z`: `i64`
- `levels`: `Vec<gizlang_meshdraw.Gaussians>`

### `View`

```gizlang
type View = { eye: Point3; target: Point3; up: Point3; fov: f64; width: i64; height: i64; }
```

A camera a tile's collider is seen through: its EYE, what it looks at, its UP, its vertical FOV (radians) and its
picture's WIDTH and HEIGHT; a depth renderer gives each pixel's distance along its ray (pixel centers at +0.5, the
top row first).

- `eye`: `gizlang_geometry.Point3`
- `target`: `gizlang_geometry.Point3`
- `up`: `gizlang_geometry.Point3`
- `fov`: `f64`
- `width`: `i64`
- `height`: `i64`

## Functions

### `captureOf`

```gizlang
function captureOf(data: bytes, name: string): Capture throws string
```

The capture of its index file's bytes DATA, JSON (named NAME in an error).

Effects: fail, alloc.

### `standOf`

```gizlang
function standOf(solid: Vec<Point3>, eyes: Vec<Point3>, ups: Vec<Point3>, forward: Point3): Stand throws string
```

How the place whose solid points are SOLID stands in a game (EYES the cameras' places, in the video's frame, meters):
the ground under the eyes is the plane y 0, +y up from it, the first camera's view FORWARD is -z (the north), and
the first eye stands over the origin. The ground is the plane through most of the points within 4 m of the cameras'
path and from 0.3 to 15 m under it, found by random samples of three (RANSAC: within 8 cm, tilted at most 37 degrees
from UPS, the cameras' mean up, which a video's pitch skews by several degrees).

Effects: fail, alloc.

### `leveled`

```gizlang
function leveled(s: Gaussians, eyes: Vec<Point3>, ups: Vec<Point3>, forward: Point3, sky: f64 = 60.0): Leveled throws string
```

The place S (in the frame its video was posed in, meters) as a game stands in it (standOf, its solid splats the
points). A splat farther than SKY meters from every camera is the sky the video saw (its depth's far end) and is
left out: a map draws its own sky. Colors keep degree 1, turned with the place.

Effects: fail, alloc.

### `tiled`

```gizlang
function tiled(s: Gaussians, cell: f64, levels: i64): Vec<Cut>
```

S cut into tiles of CELL meters, each with LEVELS levels of detail (merged), the tiles in the order of their cells.

Effects: fail, read, write, console, io, alloc.

### `merged`

```gizlang
function merged(s: Gaussians, voxel: f64): Gaussians
```

The splats of S merged within cubes of VOXEL meters, one a cube, of degree 0: each the moments of what it merges,
weighed by opacity and area (its center the mean, its covariance theirs and their spread), its color their mean,
and its opacity their opacity times area over its own area, at most 0.99.

Effects: fail, read, write, console, io, alloc.

### `views`

```gizlang
function views(x: i64, z: i64, cell: f64, low: f64, high: f64, stride: f64 = 32.0, side: i64 = 256): Vec<View>
```

The views a collider of the tile at cell X, Z (CELL meters, its splats from LOW to HIGH meters up) is fused from:
at every STRIDE meters across it, at a walker's eye (1.7 m over LOW) and over the roofs (HIGH), looking each way
of the compass and straight down, each 90 degrees wide in SIDE pixels.

Effects: fail, alloc.

### `collider`

```gizlang
function collider(views: Vec<View>, distances: Vec<f32>, alpha: Vec<f32>, box: Bounds3, voxel: f64, most: i64, bands: f64 = 2.0): Gltf.Written
```

The collider of what VIEWS saw: each view's DISTANCES and ALPHA (a map a view, one after another), fused in
cubes of VOXEL meters inside BOX into a signed distance (each covered pixel's ray marks a band of BAND voxels
about its surface, wider where the depths are noisier: in front positive, behind negative, averaged), whose zero is the surface (surface nets: a vertex
a cube the surface crosses, at the mean of its edges' crossings, a quad an edge it crosses), with about MOST
triangles (quadric simplify; no edge collapses past 0.1 m of error, and the tile's border stays).

Effects: fail, read, write, alloc.

### `levelOf`

```gizlang
function levelOf(capture: Capture, tile: Tile, eye: Point3): i64
```

The level of TILE that CAPTURE draws seen from EYE (its reach past the eye's distance to the tile's middle, on the
ground), or -1 when the tile is past the last reach.

Effects: fail.

## Methods

### `Stand.placed`

```gizlang
function Stand.placed(self: Stand, p: Point3): Point3
```

The point P of the video's frame where the game has it.

