Document Figure Recovery

FEMIC can wrap the UBC-FRESH figrecover package for document-ingestion workflows where published figures contain useful evidence but the source data tables were not released.

This workflow is optional. Normal FEMIC installation, THLB reconstruction, VDYP, TIPSY, BatchTIPSY, Patchworks, and instance-scaffold workflows do not require figrecover.

Install

Install figrecover from its source repository only on workstations that will prepare or review document figures:

python -m pip install "figrecover[pdf,cv,vlm] @ git+https://github.com/UBC-FRESH/figrecover.git@v0.1.0a1"

The femic[figures] extra is retained as a PyPI-safe compatibility marker, but it does not install figrecover while figrecover has no PyPI distribution.

Then verify the optional stack:

femic doc figures preflight

The preflight command reports whether figrecover plus its PDF/image dependencies are importable. It does not download or process documents.

Corpus Layout

FEMIC writes generated document-ingestion artifacts under ignored runtime paths:

runtime/document_ingestion/<corpus_id>/
  source_manifest.yaml
  pages/
  figure_candidates.csv
  crops/
  calibration/
  recovered/
  overlays/
  review_manifest.jsonl
  accepted/

Rendered pages, crops, overlays, prompt logs, raw recovered tables, and review bundles should stay under ignored runtime paths unless a maintainer explicitly approves a sanitized public artifact.

Prepare A Corpus

Use prepare-corpus to initialize the corpus layout and render selected public PDF pages through figrecover:

femic doc figures prepare-corpus tfl6-mp11-pilot \
  --pdf /path/to/TFL6_MP_11_202606_w_Appendices_Web-compressed.pdf \
  --pages 82-86,91,98-100,103,116,123 \
  --dpi 150 \
  --output-root runtime/document_ingestion/tfl6-mp11-pilot

The command writes source_manifest.yaml with source checksums, render metadata, and artifact paths. If supplied with a figrecover JSONL figure manifest, it also writes a compact figure_candidates.csv summary for FEMIC planning and review.

Register A Recovered Table

FEMIC does not treat recovered values as accepted model inputs by default. After a user has recovered and reviewed a table, register the table with explicit provenance:

femic doc figures register-table tfl6-mp11-pilot recovered.csv \
  --document-title "TFL 6 Management Plan 11" \
  --page 82 \
  --figure-id "Figure 2" \
  --series-name "base case" \
  --visual-selection-rule "blue harvest-flow line" \
  --calibration-spec calibration/figure-2.json \
  --extraction-method deterministic_line_mask \
  --extraction-parameters recovered/figure-2-params.json \
  --source-url https://www.westernforest.com/wp-content/uploads/2026/06/TFL6_MP_11_202606_w_Appendices_Web-compressed.pdf \
  --review-status accepted_for_comparison \
  --downstream-use comparison_evidence \
  --reviewer "Reviewer Name" \
  --output-root runtime/document_ingestion/tfl6-mp11-pilot

The command appends a JSONL record to review_manifest.jsonl and writes a formatted JSON sidecar under recovered/. It computes checksums for the registered table and, when supplied, local source and crop artifacts.

Review Gates

FEMIC review statuses are deliberately conservative:

  • raw_extraction

  • needs_calibration_review

  • needs_value_review

  • reviewed_for_planning

  • accepted_for_comparison

  • accepted_for_model_input

  • rejected

  • superseded

Reviewed or accepted statuses require a reviewer and review timestamp. Raw figure-recovery outputs cannot silently become accepted model inputs.

TFL 6 MP11 Pilot

The first pilot manifest is tracked as public-safe planning material:

  • planning/phase78_tfl6_mp11_pilot_notes.md

  • planning/phase78_tfl6_mp11_pilot_figure_manifest.csv

The pilot aligns with the TFL 6 instance Phase 6 issue tree:

  • UBC-FRESH/femic-tfl6-instance#42

  • UBC-FRESH/femic-tfl6-instance#43

  • UBC-FRESH/femic-tfl6-instance#44

The pilot manifest is not a recovered data product. It only records selected figure candidates, page anchors, chart families, recovery objectives, and review expectations.