Files
faunosteo/docs/PDF-FORMAT.md
T

2.9 KiB
Raw Blame History

PDF Format

Placeholder — to be written when implementing src/pdf/.

Will cover:

  • A4 portrait dimensions (595.28 × 841.89 pt)
  • Page layout: header / body / footer zones
  • Observation page structure
  • Conclusion page structure
  • JSON attachment spec (EmbeddedFiles, afRelationship:Data)
  • Font handling (pdf-lib StandardFonts Helvetica/Times-Roman, WinAnsi; TTF Inter/Fraunces planned, not shipped)
  • Import/re-import roundtrip contract

Attachment versions (Step 5)

The attachment osteo-report.json carries the Report v3 document (packages/domain/src/report/v3.ts): zones by (annotationId, viewId), findings by (findingZoneId, path) with label snapshots, severity codes, the sheet reference (sheet id, version id, sha256 of the document) and the reserved localAnnotations.

Import (importReportFromPdf(bytes, migrationMap)) accepts:

  • v3: read as is;
  • v2 (PDFs produced by the application before Step 5, the practitioner's archive): migrated through the sheet's report-migration-map.json; a zone or finding the map cannot place is kept with its snapshots and flagged unresolved: true; the outcome reports migrated and the unresolved counts;
  • any other version: ImportError('incompatible_version', foundVersion).

Checking an archive against its migration

pnpm report:compare <file.pdf | folder>... reads the attachment of one or more PDFs and prints it next to its v3 reading on the bundled reference sheet. It writes no output file:

  • a v2 archive PDF: every legacy zone (data-anno-id, side, vertebrae) and every legacy finding path is shown with its canonical target and the current label of that target (same when the path did not change);
  • a v3 PDF: every zone and finding is checked against the sheet, and the header says whether the report was written on the bundled sheet document;
  • anything the sheet cannot place is printed as !! UNRESOLVED with the reason: unknown legacy zone id, finding removed from the sheet by the curation, finding that never belonged to the legacy catalog, or a v3 finding flagged unresolved in the report itself.

Options: --summary (one line per file, counts and unresolved counts), --full (add the practitioner, animal and owner names and the real free texts; by default only identifiers, catalog labels, snapshots of unresolved items, counts and placeholders such as comment (present) are printed), --locale fr|en (labels), --diff a.pdf b.pdf (compare the v3 content of two PDFs: an archive and the PDF exported after importing it should print identical v3 content; by default the texts are compared as placeholders, so an edited text shows only when it appears or disappears; --full compares the real texts and prints the differing lines). Every untrusted string is printed with control characters escaped as \uXXXX. The tool exits 2 when a file could not be read (no attachment, unknown version, oversized) and prints the reason.