# S01: Core Pipeline — Preprocessing + Vectorization

**Goal:** Stand up FastAPI server with OpenCV preprocessing pipeline and dual-mode vectorization (Potrace + VTracer). Establish the repo structure, dependencies, and core /engine/trace endpoint.
**Demo:** After this: POST /engine/trace with a PNG logo returns valid SVG using both Potrace and VTracer modes

## Tasks
- [x] **T01: Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified** — 1. Create the repo directory structure at /vmPool/r/repos/xpltdco/kerf/
2. Set up engine/ as a Python project with pyproject.toml
3. Pin dependencies: fastapi, uvicorn, opencv-python-headless, pypotrace, vtracer, python-multipart, Pillow
4. Create engine/main.py with FastAPI app skeleton
5. Create engine/requirements.txt or use pyproject.toml deps
6. Add .gitignore, initial README.md
7. Verify: pip install works, uvicorn starts the empty app
  - Estimate: 30min
  - Files: engine/pyproject.toml, engine/main.py, engine/requirements.txt, .gitignore, README.md
  - Verify: cd engine && pip install -e . && uvicorn main:app --host 0.0.0.0 --port 8000 & sleep 3 && curl -s http://localhost:8000/docs | head -20
- [x] **T02: OpenCV preprocessing pipeline** — 1. Create engine/pipeline/preprocessing.py
2. Implement preprocessing stages in order:
   - Grayscale conversion
   - Denoise (bilateral filter, tunable d/sigmaColor/sigmaSpace)
   - Contrast enhancement (CLAHE, tunable clipLimit/tileGridSize)
   - Threshold (Otsu auto-threshold default, manual override)
   - Edge detection (optional Canny, tunable thresholds)
   - Morphological ops (dilation/erosion, tunable kernel size/iterations)
3. Each stage tunable via parameters dict
4. Pipeline accepts raw image bytes, returns processed numpy array
5. Add unit tests for each stage
  - Estimate: 45min
  - Files: engine/pipeline/__init__.py, engine/pipeline/preprocessing.py, engine/tests/test_preprocessing.py
  - Verify: cd engine && python -m pytest tests/test_preprocessing.py -v
- [x] **T03: Potrace vectorization (Mode A)** — 1. Create engine/pipeline/vectorize.py
2. Implement potrace_trace() function:
   - Accepts preprocessed numpy array (binary image)
   - Calls pypotrace with tunable params: turdsize, alphamax, opticurve, opttolerance
   - Returns SVG string
3. Handle potrace bitmap creation from numpy array
4. Test with a clean high-contrast test image
5. Verify SVG output is well-formed
  - Estimate: 45min
  - Files: engine/pipeline/vectorize.py, engine/tests/test_vectorize.py, engine/tests/fixtures/
  - Verify: cd engine && python -m pytest tests/test_vectorize.py -v -k potrace
- [x] **T04: VTracer vectorization (Mode B)** — 1. Add VTracer tracing to engine/pipeline/vectorize.py
2. Implement vtracer_trace() function:
   - Accepts preprocessed image (can be color for VTracer)
   - Calls vtracer with tunable params: colormode, hierarchical, filter_speckle, color_precision, layer_difference, corner_threshold, length_threshold, splice_threshold
   - Returns SVG string
3. Research vtracer Python bindings — may need vtracer pip package or subprocess
4. Test with photographic/noisy input
5. Compare Mode A vs Mode B output on same input
  - Estimate: 45min
  - Files: engine/pipeline/vectorize.py, engine/tests/test_vectorize.py
  - Verify: cd engine && python -m pytest tests/test_vectorize.py -v -k vtracer
- [x] **T05: Wired POST /engine/trace endpoint with preprocess + vectorize pipeline, SVG metadata, and 14 integration tests** — 1. Create engine/api/routes.py with trace endpoint
2. POST /engine/trace accepts multipart/form-data:
   - file (image), mode (potrace|vtracer), output_format (svg only for now), preset (ignored for now), params (JSON override)
3. Wire pipeline: receive file → preprocess → vectorize (mode-dependent) → return SVG + metadata
4. Response shape: {output: '<svg>...', format: 'svg', metadata: {path_count, node_count_total, open_paths, warnings, processing_ms}}
5. Add basic metadata extraction from SVG output
6. Integration test: upload PNG → get SVG back
  - Estimate: 45min
  - Files: engine/api/__init__.py, engine/api/routes.py, engine/main.py, engine/tests/test_api.py
  - Verify: cd engine && python -m pytest tests/test_api.py -v
