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
  envs/               conda environment specs for task and MMSeg runtimes
  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

# Create or repair the two runtime environments, then verify imports.
scripts/bootstrap_conda_envs.sh

# 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. Selecting an uploaded dataset fills task JSON with its images, labels,
and masks directories. The dataset panel validates image/label/mask pairing,
checks YOLO txt labels and mask dimensions, and can generate a `dataset.yaml`
for the `yolo.train_custom` task. The selected upload dataset also exposes
direct YOLO custom train, predict, and heatmap actions; custom outputs are
written under `var/custom_yolo_runs` and are scanned by the results dashboard.
When a dataset is selected, the dataset panel shows its custom YOLO `best.pt`,
prediction previews, heatmap previews, and inline training curve previews.
Segmentation previews, YOLO heatmaps, and loss/metric artifacts are grouped on
the results dashboard. The artifact browser loads the full result scan, can
filter by model family and artifact role, and YOLO-style `results.csv` files
are parsed into lightweight training curves.
Job APIs and the SSE log stream also expose structured progress parsed from
YOLO, MMSeg/MMEngine, SegModel-style epoch logs, and generic tqdm percentages,
so the queue and live log panel can show stage, epoch/iteration, and percent
without changing the original training scripts. Starting any web job or
dataset YOLO shortcut automatically opens its live log; the SSE stream resumes
from the current log size after the initial tail so existing lines are not
duplicated in the panel.
The task builder also reads `GET /api/system/gpus` and lets an operator choose
CPU or one or more GPUs before launch. Selected GPUs are passed to the backend
as `gpus`, exported as `CUDA_VISIBLE_DEVICES`, and reflected into YOLO/visual
`device` parameters and MMSeg config-generation `gpu_count/gpu_ids`.
The same job launcher reads `GET /api/system/envs` and provides an Auto/manual
conda environment selector. Auto keeps the backend defaults (`seg_smp` for
general SegModel/YOLO/dataset tasks and `seg_mmcv` for MMSeg); manual mode
sends `conda_env` with the job request for custom algorithm environments.

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 runtime panel calls `GET /api/system/readiness` and verifies the conda
imports required for the backend/task environment and the full MMSeg/mmcv
environment. Command-line verification is available with
`PYTHONPATH=backend conda run -n seg_smp python scripts/verify_runtime_envs.py --refresh`.
The capability matrix calls `GET /api/capabilities` and summarizes readiness
for Dataset, SegModel, YOLO, MMSeg, visual tools, analysis, and system
operations, including task coverage, runtime status, uploaded datasets,
heatmap/segmentation artifacts, training curves, and weight manifest status.

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 launches
`yolo.predict_custom` and `yolo.heatmap_custom` through the normal job queue
against the uploaded sample image, proving that upload datasets can produce
browsable segmentation and heatmap artifacts. 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.

For stronger runtime proof, `POST /api/acceptance/deep` runs minimal training
loops for the three model families: one SegModel optimizer step, one YOLO
segmentation epoch on a synthetic 64x64 dataset, one YOLO GradCAM heatmap
generation pass from the trained tiny checkpoint, and one MMSeg optimizer step
through the full `mmcv._ext` runtime. It also writes tiny SegModel mask/loss
artifacts, YOLO heatmap/results artifacts, and MMSeg loss artifacts under
`var/acceptance/deep_*`, so the normal results and curve dashboards can prove
each model family produced browsable output. The latest report is available
from `GET /api/acceptance/deep/latest` and is surfaced in the coverage panel.

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.
The reproducible specs live in `envs/seg_smp.yml` and `envs/seg_mmcv.yml`;
the bootstrap script uses the same pinned package sources:

```bash
scripts/bootstrap_conda_envs.sh all
scripts/bootstrap_conda_envs.sh task
scripts/bootstrap_conda_envs.sh mmseg
```

## 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.train_custom`, `yolo.predict_custom`, `yolo.heatmap`,
  `yolo.heatmap_custom`, `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.
Use `GET /api/capabilities` to inspect the grouped full-function readiness
matrix used by the web dashboard and agents.
Use `GET /api/results?limit=1000` to inspect browsable artifacts and
`GET /api/results/curves?limit=100` to inspect parsed training curves
discovered from YOLO, SegModel, MMSeg, visual-tool, and analysis output
directories.
Use `GET /api/agents/evaluate` and `GET /api/agents/validate` to surface the
same evaluation and validation feedback shown in the web dashboard Agent panel.

## 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 grouped capability matrix,
the `seg_smp` task env, the `seg_mmcv` MMSeg env, runtime import readiness,
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. By default it
also runs the deep training acceptance; set `SEG_VALIDATE_DEEP=0` when a quick
non-training validation pass is needed.

The web dashboard calls validation in light mode by default:
`/api/agents/validate?run_build=false&run_acceptance=false&run_deep=false`.
Pass `run_acceptance=true` or `run_deep=true` only when you explicitly want the
agent to launch the heavier runtime acceptance checks from the browser/API.