40 خطوط
6.1 KiB
Markdown
40 خطوط
6.1 KiB
Markdown
# Rendering validation and release gate
|
||
|
||
Passing a parser test is not proof that a schematic matches Altium. The service separates format acceptance, supported-subset decoding, SVG generation, interactive behavior and trusted-reference fidelity.
|
||
|
||
## Tests
|
||
|
||
`./scripts/check.sh` runs bounds/framing/version/ownership/coordinate/part visibility tests, native-file integration when fixtures are present, safe SVG serialization, embedded raster expansion controls, upload/authentication/expiry/status/error flows, subprocess worker execution, queue capacity/claims/lease recovery, stale-worker fencing, expired artifact cleanup, and a botocore-validated S3 contract. Node's built-in runner checks sheet fit, camera invariants, point-under-cursor zoom and scale limits without frontend dependencies.
|
||
|
||
`python scripts/fetch-fixture.py` downloads an actual native OLE fixture from KiCad QA and enforces SHA-256 `e7dc42a4e983e6b716f6883eb0863fe47164d941636e11b1f2b5ec5d0143dca4`. It remains ignored and is not redistributed in Docker/source. `SCHDOC_SAMPLE` enables an additional actual design. Missing native files cause explicit skipped tests; they are not replaced by synthetic circuits. CI fetches the real fixture before tests.
|
||
|
||
`python scripts/corpus.py DIRECTORY` audits every SchDoc in a directory and writes source hashes, record counts, SVG sizes, failures and diagnostics. This detects format regressions across an actual design corpus without claiming visual equivalence.
|
||
|
||
## Trusted-reference procedure
|
||
|
||
1. Select representative designs containing rotated/mirrored and multi-part components; fractional placements; all pin orientations/decorations; buses/net labels; hierarchical ports; curves/fills; text/font variants; images; standard/custom/portrait sheets; dense and large pages. Include actual supported Altium versions and retain source SHA-256 values.
|
||
2. In licensed Altium Designer, open each source and export a full-sheet reference PDF or PNG. Preserve original colors, dimensions and clipping. Record the exact Altium version, document settings, font versions, export options, page dimensions and export hash. Do not use a screenshot with toolbars or an arbitrary zoom/crop.
|
||
3. Install licensed matching fonts on the validation host and configure equivalent webfonts for the browser. Rasterize PDF references with `pdftoppm` when necessary, retaining DPI/page size. No image-recognition step replaces parsing.
|
||
4. Run `.venv/bin/python scripts/validate.py design.SchDoc --reference reference.png --output validation-output/design`. The render uses exactly the reference pixel dimensions and rejects incompatible aspect ratios. It does not fit to content or align away positional differences.
|
||
5. Review `rendered.png`, `drawing.svg`, `difference.png`, `overlay.png` and `report.json`. The tool reports mean absolute RGB error (0–255) and the fraction of pixels whose maximum channel difference exceeds a tolerance. Default thresholds are MAE ≤ 2, changed fraction ≤ 1%, channel tolerance 12; tune and freeze them against accepted references, not failing candidates. It exits nonzero when thresholds fail. White/background-heavy images can hide local errors in global metrics, so manual/local-region review is mandatory.
|
||
6. Compare native object anchors, pin endpoints, component symbol bounds, page dimensions, stroke widths, colors, rotations and textual baselines against measured reference values. Assert these coordinates independently in unit tests. Visually inspect actual browser renders, not only Cairo output, across target browser/OS/font combinations.
|
||
7. Check initial sheet fit, drag, wheel, touch pinch, resize/aspect ratio, long-lived expiry, load/error states and a dense-file performance budget in connected desktop/mobile browsers. Loaded viewers must contain no toolbar, information panel, header or footer.
|
||
8. Accept a format/version only after geometry checks, trusted visual comparisons and browser checks pass. Keep known failures as explicit compatibility restrictions. Pixel similarity alone does not prove electrical equivalence or universal pixel-perfect compatibility.
|
||
|
||
Even a passing comparison records `fidelity_verified: false`: automated image thresholds are a regression signal, not an automatic Altium-certification flag. Human review and the chosen supported-version corpus define a release's acceptance scope. Regenerate references only through a reviewed Altium export workflow.
|
||
|
||
## Evidence from this implementation session (2026-11-05)
|
||
|
||
- Final test run: 73 Python tests and 3 camera tests passed, including the native fixtures and a regression-harness test that detects altered pixels.
|
||
- 13 actual local LTE 6 SchDoc files parsed and serialized to SVG without fatal errors; results and per-file diagnostics are in ignored `.runtime/corpus.json`. Counts range from 81 to 5,342 records. This is format coverage evidence, not visual acceptance.
|
||
- The CPU sheet parsed 1,942 records and 25 components into 1,002 drawables; source SHA-256 `d6a73f11a4239eaf7e8f280ed35b82e9fd497a4680a60027cc93f266c5c006ae`.
|
||
- The public Channel fixture parsed 99 records and 2 components into 34 drawables.
|
||
- Both native sheets were rasterized with CairoSVG; the CPU PNG was visually inspected. Inspection found parameter glyph mirroring, which was corrected and regression-tested.
|
||
- Eight simultaneous actual HTTP uploads to PostgreSQL produced eight unique IDs and all completed; this also passed with two worker replicas.
|
||
- A built, non-root, read-only Compose API/worker with actual PostgreSQL completed the CPU upload/status/data/SVG flow over HTTP; private reads without a token returned 404. The published socket was confirmed at `127.0.0.1:8000`.
|
||
- S3 request/response contracts are tested with botocore stubs; a live S3 provider has not been exercised.
|
||
- No connected browser was available, so actual wheel/drag/touch behavior and browser font appearance remain unverified.
|
||
- No trusted Altium export was supplied or available in this session. No reference comparison, visual equivalence, Altium release certification or pixel-perfect claim has been made.
|
||
|
||
The implementation is operationally testable; its known rendering gaps must be resolved and reference-tested before a production deployment requiring faithful Altium reproduction.
|