# Triangulation API

Beyond the GUI interface, Caliscope provides a Python API for programmatically triangulating 2D points based on a calibrated camera array. This is intended for batch processing, custom workflows, or integration with other tools.

## Basic Usage

The core function for triangulation is `triangulate_from_files()`, which takes paths to your configuration file and 2D point data, then returns triangulated 3D points. With an optional argument these can be saved to a `csv`.

```python
from pathlib import Path
from caliscope.triangulate.triangulation import triangulate_from_files

# Define paths
config_path = Path("/path/to/project/config.toml")
xy_path = Path("/path/to/project/xy_data.csv")
output_path = Path("/path/to/project/xyz_data.csv")

# Perform triangulation
xyz_data = triangulate_from_files(
    config_path=config_path,
    xy_path=xy_path, 
    output_path=output_path
)

print(f"Triangulated {len(xyz_data)} points")
```

## Parameter Details

### Inputs  

`config_path` : Path to `config.toml` containing camera calibration parameters. You can find this file in the root of the project workspace. 

`xy_path` : Path to CSV file with 2D point data. The CSV must contain these columns:

- sync_index: Integer identifying the synchronized frame number across cameras
- port: String or integer identifying which camera captured the point
- point_id: Integer identifying which landmark/point is being tracked
- img_loc_x: Float X-coordinate in the image (in pixels)
- img_loc_y: Float Y-coordinate in the image (in pixels)

Each row represents a single 2D point observed by a specific camera at a specific time. Multiple cameras observing the same point_id at the same sync_index enables triangulation.

`output_path`(optional): Path where triangulated 3D points will be saved as a CSV file.  If not provided, results are returned but not saved to disk. The function will create parent directories if they don't exist.

### Returned Value

Pandas dataframe containing triangulated 3D points with columns:

- sync_index: Integer identifying the synchronized frame number
- point_id: Integer identifying which landmark/point was triangulated
- x_coord: Float X-coordinate in 3D space 
- y_coord: Float Y-coordinate in 3D space 
- z_coord: Float Z-coordinate in 3D space 

Each row represents a single 3D point at a specific time.  The coordinates are in the world coordinate system defined during the calibration process.

### Notes

- For successful triangulation, each point_id must be visible in at least
  two cameras at the same sync_index.
- Points that cannot be triangulated (due to insufficient camera views)
  will not appear in the output DataFrame.
- The pipeline is fairly "raw" and would benefit from 2D gap filling prior to triangulation and subsequent gap filling and smoothing.