Seg_Data_Server_Net/README.md

# Seg Data Server Net

Modular web control plane for the existing Seg image segmentation workspace.

The platform keeps the current training and analysis scripts as the compute
core, then adds:

- a FastAPI backend for catalog discovery, job orchestration, logs, results,
  GPU status, and weight management;
- a React/Vite frontend for launching jobs and inspecting progress;
- a unified `weights/` area with a generated manifest for `.pt`, `.pth`,
  `.onnx`, and `.engine` assets.

## Layout

```text
Seg_Data_Server_Net/
  backend/            FastAPI API, job runner, module wrappers
  frontend/           React + Vite operator UI
  scripts/            helper scripts for running services and syncing weights
  weights/            copied model weights and manifest.json
```

## Quick Start

```bash
cd Seg_Data_Server_Net
cp .env.example .env

# Backend. The deployment env is seg_smp so the API and most task wrappers
# share the same segmentation dependency stack. MMSeg jobs default to the
# separate SEG_MMSEG_CONDA_ENV because full mmcv wheels must match torch/CUDA.
conda run -n seg_smp uvicorn app.main:app --app-dir backend --host 0.0.0.0 --port 8010

# Frontend.
cd frontend
npm install
npm run dev -- --host 0.0.0.0
```

Open the Vite URL shown in the terminal. The frontend expects the backend at
`http://localhost:8010` by default.

The web UI includes a dataset bench for creating upload workspaces, uploading
images/labels/masks, and jumping into the existing rename, PNG conversion,
resize, pair-check, label rebuild, transparent overlay, stitch, and video-frame
jobs. Segmentation previews, YOLO heatmaps, and loss/metric artifacts are
grouped on the results dashboard.

The coverage panel calls `GET /api/coverage` and verifies that the user-facing
scripts from the existing `Seg/` workspace are mapped to web jobs. MMSeg
vendored internals, docs, build outputs, converters, and config templates are
classified as supporting artifacts rather than direct web actions.

The same panel can run `POST /api/acceptance/smoke`, a lightweight live smoke
that creates an upload dataset, uploads a label, downloads it through the
artifact API, runs a mock job, checks SSE log streaming, and executes one
legacy image/label overlay job on tiny generated PNGs. It also runs model
family readiness checks: a SegModel/SMP forward pass, a YOLO segmentation
prediction on a tiny image, MMSeg config parsing, and local MMSeg pretrained
weight discovery. MMSeg full-model readiness is validated in
`SEG_MMSEG_CONDA_ENV` by importing `mmcv._ext` and building a local MMSeg
`EncoderDecoder` from the existing config tree.

Current `seg_smp` uses `mmcv-lite` because no `torch 2.6/cu124` full `mmcv`
wheel is available on this machine and `nvcc` is not installed for source
builds. A dedicated `seg_mmcv` environment is used for MMSeg tasks and has
`torch 2.1.2+cu121`, `mmcv 2.1.0`, `mmsegmentation 1.2.2`, and NumPy 1.26.
If rebuilding the environment, keep these versions aligned:

```bash
conda create -n seg_mmcv python=3.10 -y
conda run -n seg_mmcv python -m pip install -U pip
conda run -n seg_mmcv python -m pip install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu121
conda run -n seg_mmcv python -m pip install mmengine==0.10.7 mmsegmentation==1.2.2 'mmcv==2.1.0' -f https://download.openmmlab.com/mmcv/dist/cu121/torch2.1/index.html
conda run -n seg_mmcv python -m pip install 'numpy<2' 'opencv-python<4.12' ftfy regex matplotlib pandas scikit-learn scipy seaborn tqdm tensorboard
```

## Weight Sync

The current workspace contains tens of GB of pretrained and trained weights.
They are copied into `weights/files/<original-relative-path>` and indexed in
`weights/manifest.json`.

```bash
cd Seg_Data_Server_Net
python scripts/sync_weights.py --mode copy --hash
```

Weights must remain local to the deployment machine. Do not push `.pt`, `.pth`,
`.onnx`, `.engine`, or `weights/files/` into Gitea. The repository stores only
code, `weights/manifest.json`, and helper scripts. Before pushing, run:

```bash
scripts/check_no_weight_git.sh
```

If a deployment machine needs weights, run the sync command locally on that
machine after cloning the code.

## Job Types

The backend exposes all current Seg capabilities as job types. Examples:

- `dataset.rename`, `dataset.resize`, `dataset.pair`, `dataset.rebuild_labels`,
  `dataset.stack`, `dataset.stitch`, `dataset.video_frames`,
  `dataset.yolo_check_pairs`, `dataset.yolo_stack`, `dataset.yolo_txt_sort`,
  `dataset.yolo_convert_png`, `dataset.yolo_resize`
- `segmodel.train`, `segmodel.batch_train`, `segmodel.predict`,
  `segmodel.batch_predict`, `segmodel.flops`, `segmodel.params_flops`,
  `segmodel.benchmark`, `segmodel.raw_mask_check`
- `yolo.train`, `yolo.batch_train`, `yolo.predict`, `yolo.batch_predict`,
  `yolo.heatmap`, `yolo.compare`, `yolo.raw_mask_check`, `yolo.video_visible`
- `mmseg.generate_data`, `mmseg.generate_alg`, `mmseg.train`,
  `mmseg.metrics`, `mmseg.flops_fps`, `mmseg.draw`, `mmseg.extract_loss_miou`
- `visual.train`, `visual.inference`, `visual.fps`,
  `visual.yolo11_heatmap_v1`, `visual.yolo11_heatmap_v2`, `visual.deal_labels`
- `analysis.all`, `system.backup`, `mock.echo`

Use `GET /api/catalog` to inspect supported models, algorithms, datasets, and
task types discovered from the existing `Seg/` workspace.
Use `GET /api/coverage` to inspect script-to-task coverage and task
buildability.

## Agents

Run the local evaluation and validation agents before publishing changes:

```bash
PYTHONPATH=backend conda run -n seg_smp python scripts/run_agents.py --build
```

The validation agent checks catalog coverage, the `seg_smp` task env, the
`seg_mmcv` MMSeg env, GPU visibility, no-weight Git safety, backend tests,
frontend build, and live backend/frontend endpoints when the services are
running. With live validation enabled it also runs the lightweight acceptance
smoke above.