# Bulk Engine API

Bulk Engine provides batch analytics and visualization endpoints for cell data
stored in the database (table `cells`). All routes are served under the backend
API prefix: `/api/v1`.

## Base URL

```
http://<host>:<port>/api/v1
```

## Requirements

- Python 3.10+ (root README uses Python 3.14)
- Install backend deps: `pip install -r backend/requirements.txt`
- SQLite database with a `cells` table (generated by the Cell Extraction API)

## Libraries

<p align="left">
  <a href="https://fastapi.tiangolo.com/" title="FastAPI">
    <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/fastapi/fastapi-original.svg" height="32" alt="FastAPI" />
  </a>
  <a href="https://www.sqlalchemy.org/" title="SQLAlchemy">
    <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/sqlalchemy/sqlalchemy-original.svg" height="32" alt="SQLAlchemy" />
  </a>
  <a href="https://numpy.org/" title="NumPy">
    <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/numpy/numpy-original.svg" height="32" alt="NumPy" />
  </a>
  <a href="https://opencv.org/" title="OpenCV">
    <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/opencv/opencv-original.svg" height="32" alt="OpenCV" />
  </a>
  <a href="https://matplotlib.org/" title="Matplotlib">
    <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/matplotlib/matplotlib-original.svg" height="32" alt="Matplotlib" />
  </a>
</p>

- FastAPI for routing and responses
- SQLAlchemy for SQLite access
- NumPy and OpenCV for numerical and image processing
- Matplotlib for PNG plot rendering
- Pydantic for response models

## Common Query Parameters

- `dbname` (required): database file name, e.g. `example.db`
- `label` (optional): filter by manual label
  - empty or `all` disables filtering
  - `N/A` matches both `N/A` and `1000`
- `channel`:
  - heatmap endpoints: `fluo1 | fluo2`
  - intensity endpoints: `ph | fluo1 | fluo2`
- `degree` (heatmap and cell width endpoints): integer >= 1
- `center_ratio` (HU separation overlay): float 0.0-1.0
- `max_to_min_ratio` (HU separation overlay): float >= 0.0

## Endpoints

### Heatmap and Visualization

**GET** `/get-heatmap-vectors-csv`  
Returns CSV bytes for heatmap vectors (u1/G pairs per cell).  
Params: `dbname`, `label`, `channel`, `degree`  
Response: `text/csv`

**GET** `/get-heatmap-abs-plot`  
Absolute heatmap plot.  
Params: `dbname`, `label`, `channel`, `degree`  
Response: `image/png`

**GET** `/get-heatmap-rel-plot`  
Relative heatmap plot.  
Params: `dbname`, `label`, `channel`, `degree`  
Response: `image/png`

**GET** `/get-hu-separation-overlay`  
HU separation overlay plot.  
Params: `dbname`, `label`, `channel`, `degree`, `center_ratio`, `max_to_min_ratio`  
Response: `image/png`

**GET** `/get-map256-strip`  
Map256 strip image across cells.  
Params: `dbname`, `label`, `channel`, `degree`  
Response: `image/png`

**GET** `/get-contours-grid-plot`  
Contours grid plot aligned to the cell principal axes.  
Params: `dbname`, `label`  
Response: `image/png`

**GET** `/get-contours-grid-json`  
Transformed contour coordinates (u1/u2) keyed by `cell_id`.  
Params: `dbname`, `label`  
Response: `application/json`  
Format: `{ "cell_id": [[u1, u2], ...], ... }`

### Measurements

**GET** `/get-cell-lengths`  
Cell lengths (um) using PCA over contour.  
Params: `dbname`, `label`  
Response: JSON array of `{ "cell_id": string, "length": number }`

**GET** `/get-cell-lengths-plot`  
Boxplot for cell lengths.  
Params: `dbname`, `label`  
Response: `image/png`

**GET** `/get-cell-areas`  
Cell areas (px^2).  
Params: `dbname`, `label`  
Response: JSON array of `{ "cell_id": string, "area": number }`

**GET** `/get-cell-areas-plot`  
Boxplot for cell areas.  
Params: `dbname`, `label`  
Response: `image/png`

**GET** `/get-cell-widths`  
Mean and median centerline-to-contour distances (px) per cell.  
Params: `dbname`, `label`, `degree`  
Response: JSON array of `{ "cell_id": string, "width_mean": number, "width_median": number }`

**GET** `/get-normalized-medians`  
Normalized median intensities per cell.  
Params: `dbname`, `label`, `channel`  
Response: JSON array of `{ "cell_id": string, "normalized_median": number }`

**GET** `/get-normalized-medians-plot`  
Boxplot for normalized medians.  
Params: `dbname`, `label`, `channel`  
Response: `image/png`

**GET** `/get-raw-intensities`  
Raw intensity values inside each contour.  
Params: `dbname`, `label`, `channel`  
Response: JSON array of `{ "cell_id": string, "intensities": number[] }`

## Example Requests

Heatmap vectors CSV:

```sh
curl -G \
  "http://localhost:3000/api/v1/get-heatmap-vectors-csv" \
  --data-urlencode "dbname=example.db" \
  --data-urlencode "label=all" \
  --data-urlencode "channel=fluo1" \
  --data-urlencode "degree=4" \
  -o heatmap.csv
```

Cell lengths (JSON):

```sh
curl -G \
  "http://localhost:3000/api/v1/get-cell-lengths" \
  --data-urlencode "dbname=example.db" \
  --data-urlencode "label=1"
```

Heatmap plot (PNG):

```sh
curl -G \
  "http://localhost:3000/api/v1/get-heatmap-abs-plot" \
  --data-urlencode "dbname=example.db" \
  --data-urlencode "label=all" \
  --data-urlencode "channel=fluo1" \
  --data-urlencode "degree=4" \
  -o heatmap.png
```

## Notes

- Heatmap endpoints use a single-worker process pool to avoid concurrent heavy
  CPU work; large datasets may take time to respond.
- Some endpoints trigger Slack notifications when configured.
- Errors:
  - `404` if the database is missing or no data is available
  - `400` for invalid parameters (e.g., unsupported channel or degree)
  - `500` for unexpected failures