diff --git a/.gitignore b/.gitignore index 86c5ea6..a6e6465 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .claude/ ~$* build/ +figures/fig5_bbqs_stack/fig5_bbqs_stack_tuned/ diff --git a/Makefile b/Makefile index 14016d8..812f707 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,7 @@ # Build generated figures and check the TODO list against the draft. # # make figures regenerate all generated figures into figures/ (paper figures and alternates) +# make fig5 Fig. 5 SVG (links, layers) from its .pptx, and its walkthrough with svgtune if installed # make alternates regenerate only the alternate figures (figures/alternates/, not in the paper) # make pdf render the full draft (draft/*.md) as build/paper.tex and build/paper.pdf for review # make check check that every [TODO-Cn] marker in draft/ has an entry in plan/TODO.md and vice versa @@ -11,9 +12,9 @@ ECOKG := $(KG)/.venv/bin/ecokg UVRUN := uv run -q --no-project --with openpyxl --with matplotlib python PDF_DATE := $(shell date +%Y-%m-%d), commit $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown) -.PHONY: figures fig3 fig4 alternates alt-kg-lenient pdf check kg-env +.PHONY: figures fig3 fig4 fig5 alternates alt-kg-lenient pdf check kg-env -figures: fig3 fig4 alternates +figures: fig3 fig4 fig5 alternates alternates: alt-kg-lenient @@ -32,6 +33,13 @@ alt-kg-lenient: $(ECOKG) fig4: $(UVRUN) analysis/bbqs_inventory.py +FIG5 := figures/fig5_bbqs_stack + +fig5: + python3 tools/pptx2svg.py $(FIG5)/fig5_bbqs_stack.yaml + @if command -v svgtune >/dev/null; then cd $(FIG5) && svgtune fig5_bbqs_stack.svgtune; \ + else echo "svgtune (https://github.com/yarikoptic/svgtune) not found: walkthrough not generated"; fi + pdf: mkdir -p build pandoc --defaults tools/pdf/defaults.yaml -M date="Review draft, $(PDF_DATE)" \ diff --git a/figures/fig5_bbqs_stack/README.md b/figures/fig5_bbqs_stack/README.md index 186c864..d3714c0 100644 --- a/figures/fig5_bbqs_stack/README.md +++ b/figures/fig5_bbqs_stack/README.md @@ -3,12 +3,12 @@ | | | |---|---| | Cited in | Section 6 | -| Status | design draft (`fig5_bbqs_stack_design.pptx`, preview `fig5_bbqs_stack_design.png`); edit the .pptx directly; final artwork by designer | +| Status | design draft (`fig5_bbqs_stack_design.pptx`, preview `fig5_bbqs_stack_design.png`); edit the .pptx directly; final artwork by designer. Generated from it: `fig5_bbqs_stack.svg`, with a link on every element, and a walkthrough (`fig5_bbqs_stack.svgtune`) | | Concept | Layers 1, 2, 3, and 5 stacked in Table 1 order; ontologies & terminologies (4) and schema languages (6) as side panels next to rows 2–3, which they both serve. Columns NWB, BIDS, Psych-DS. Each cell shows what is recommended today (solid), what is in progress (dashed; labeled by what it adds), and what needs a standard (grey, dashed). | -| Rows | 1 formats with what they hold (HDF5 · Zarr for NWB files; MP4 · AVI · MOV video linked from NWB; NIfTI · OME-Zarr; EDF · BrainVision; JSON · TSV; WAV · MP4 · PNG via BIDS PR #2367; CSV · JSON) · 2 NWB core, with extensions and enhancement proposals labeled by purpose (pose estimation = ndx-pose, structured behavior, microscopy = NWBEP004, HED annotation = ndx-hed, fiber photometry, wearable devices, multi-subject = ndx-multisubjects, ethogram); a dashed green line joins Multi-subject to the planned multi-subject BEP (planned companion proposals) · 3 DANDI layout; BIDS with BEP032, BEP047, BEP020/BEP042, multi-subject BEP; Psych-DS · 5 EMBER. Panel 4: HED; Neuro Termsets (in progress) with arrows to the terminologies it draws on; NCBI Taxonomy, UBERON, Allen atlases, RRID, ORCID · ROR, Cell Ontology, one box each; behavior labels (gap). Panel 6: HDMF → NWB, BIDS schema → BIDS, LinkML → Psych-DS and Neuro Termsets (Dandiset and NWB schema translations to LinkML planned), JSON Schema (Pydantic) → DANDI layout and EMBER archive metadata (Pydantic models in dandi/dandi-schema; JSON Schema and JSON-LD context published in dandi/schema). | -| Paths | Each data type appears once; thin lines with junction dots join it to every standard that can hold it (Table 3). Path colours by standard: NWB orange (data → NWB → EMBER), BIDS green, Psych-DS slate; data-format boxes, the DANDI layout, and Psych-DS are outlined in the colour of the path they sit on; a green arrow from NWB to the BIDS path shows that BIDS can contain NWB files (BEP032). Data without a standard (Table 3 gap row) have no path. | +| Rows | 1 formats with what they hold (HDF5 · Zarr for NWB files; MP4 · AVI · MOV video linked from NWB; NIfTI · OME-Zarr; EDF · BrainVision (EEG, iEEG, EMG; BIDS accepts only EDF and BDF for EMG); JSON · TSV; WAV · MP4 · PNG via BIDS PR #2367; CSV · JSON) · 2 NWB core, with extensions and enhancement proposals labeled by purpose (pose estimation = ndx-pose, structured behavior, microscopy = NWBEP004, HED annotation = ndx-hed, fiber photometry, wearable devices, multi-subject = ndx-multisubjects, ethogram); a dashed green line joins Multi-subject to the planned multi-subject BEP (planned companion proposals) · 3 DANDI layout; BIDS (eye tracking and EMG are in BIDS since v1.11) with BEP032, BEP047, BEP044 (stimuli), multi-subject BEP; Psych-DS · 5 EMBER. Panel 4: HED; Neuro Termsets (in progress) with arrows to the terminologies it draws on; NCBI Taxonomy, UBERON, Allen atlases, RRID, ORCID · ROR, Cell Ontology, one box each; behavior labels (gap). Panel 6: HDMF → NWB, BIDS schema → BIDS, LinkML → Psych-DS and Neuro Termsets (Dandiset and NWB schema translations to LinkML planned), JSON Schema (Pydantic) → DANDI layout and EMBER archive metadata (Pydantic models in dandi/dandi-schema; JSON Schema and JSON-LD context published in dandi/schema). | +| Paths | Each data type appears once; thin lines with junction dots join it to every standard that can hold it (Table 3). Path colours by standard: NWB orange (data → NWB → EMBER), BIDS green, Psych-DS slate; data-format boxes, the DANDI layout, and Psych-DS are outlined in the colour of the path they sit on; a green arrow from NWB to the BIDS path shows that BIDS allows NWB files for iEEG, and BEP032 would add microelectrode electrophysiology. EMG is a data type of its own, on the BIDS path only (Table 3). Data without a standard (Table 3 gap row) have no path. | | Draft choices | Styled like Fig. 2: Arial; layer rows with a light tint, coloured outline, top band, and numbered badge in the Fig. 1 colours (palette in `../fig1_ecosystem_map/README.md`); technologies as white chips outlined in their layer colour; raw data in grey (as Level 0 in Fig. 2); in-progress items as dashed chips and gaps as grey dashed boxes; paths coloured by standard; legend at the top. Each box carries its own text (one shape per item), so boxes can be moved and edited as single objects. Canvas 13.33 × 8.6 in (same width as Figs. 1 and 2, taller for the detail). Stack geometry (D8): four stacked rows (formats, file organization, dataset organization, archives) with ontologies and schema languages as side panels next to the two organization rows, which they both serve. The speaker notes describe the rows and paths. | | Source | Spec and legend in `draft/12_figures_tables.md`; content from Section 6, Table 3, the BBQS standards guideline, and the Standards4BBQS slides of the BBQS Forum (Oct 2026). Proposal status is as of Oct 2026 and must be rechecked before submission. | -| Build | Not generated; the design draft .pptx is the editable source. The PNG preview is exported at 300 dpi; re-export it after editing the .pptx. Place the final artwork here. | +| Build | The design draft .pptx is the editable source. `make fig5` writes `fig5_bbqs_stack.svg` from it with `tools/pptx2svg.py`, which adds the links and the build steps (Inkscape layers) listed in `fig5_bbqs_stack.yaml`, and, if [svgtune](https://github.com/yarikoptic/svgtune) is installed, the walkthrough `fig5_bbqs_stack_tuned/.svg` (not committed): stack, data types, the NWB path (formats, files, DANDI layout, EMBER), the BIDS path (with NWB dimmed), companion proposals, the Psych-DS path, ontologies, gaps. Rerun it after editing the .pptx, and add links for new shapes to the .yaml. The PNG preview is rendered from the SVG at 300 dpi. Place the final artwork here. | | Legend | `draft/12_figures_tables.md` (single source for all legends) | | Open tasks | `plan/TODO.md`, section "3. Figures" (F3, F10) | diff --git a/figures/fig5_bbqs_stack/fig5_bbqs_stack.svg b/figures/fig5_bbqs_stack/fig5_bbqs_stack.svg new file mode 100644 index 0000000..f2ed70a --- /dev/null +++ b/figures/fig5_bbqs_stack/fig5_bbqs_stack.svg @@ -0,0 +1,208 @@ + + + +Fig. 5: The BBQS standards stack + + + + +Recommended for BBQS + +In progress (extension or proposal) + +Needs a standard + +Path to the archive +Data archivesPublish, share, anddiscover + +5 +DatasetorganizationstandardsOrganize collectionsof files + +3 +File organizationstandardsOrganize data withina file + +2 +Data formatsMap data to storage + +1 +Ontologies &terminologiesDefine the meaning ofterms + +4 +SchemalanguagesDefine thestandards + +6 + + + + + + + + + + + + + + + + + + + + + + + + + + +EMBERaccepts NWB, DANDI-layout, BIDS, and Psych-DS datasets, with privacy levels for identifiable human data + + +HDF5 · ZarrNWB files +MP4 · AVI · MOVvideo, linked + + +NIfTI · OME-ZarrMRI, PET, microscopy +EDF · BrainVisionEEG, iEEG, EMG +JSON · TSVmetadata, tables +WAV · MP4 · PNGBIDS PR #2367 + + +CSV · JSONtables, metadata + + +NWBEphys · ophys · stimulation · behavior · videolinks · events +Pose estimation +Fiber photometry +Structured behavior +Wearable devices +Microscopy +Multi-subject +HED annotation +Ethogram + + +BIDS allows NWB foriEEG; BEP032 addsmicroelectrode ephys + + +DANDI layoutone NWB file per subject and session + + +BIDSMRI · PET · EEG / MEG / iEEG · microscopy· motion · physiology · eye tracking · EMG ·behavior and task events · stimuli +BEP032microelectrode ephys +BEP047behavior recordings +BEP044stimuli + + +Multi-subject BEPplanned + + +Psych-DSevery variabledefined in JSON + + + + +Planned companionproposals + + +HEDannotates events in BIDS, NWB +Neuro Termsetsterm sets for NWB and BIDS +NCBI Taxonomy species + +UBERON anatomy + +Allen atlases brain regions + +RRID strains + +ORCID · ROR people, labs + +Cell Ontology cell types + + + +Behavior labelsno shared vocabulary in use + + +HDMFdefines NWB + + +BIDS schemadefines BIDS + + +LinkMLdefines Psych-DSand Neuro Termsets(Dandiset and NWBschema translationsplanned) + + +JSON Schema(Pydantic)defines DANDIlayout, EMBERarchive metadata + + +BBQS data types: +Electro- and opticalphysiology ·stimulation +Video · audio · pose ·eye tracking · taskevents +EEG · MEG ·iEEG +MRI · fMRI ·PET +Wearables +Questionnairessurveys + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +EMG + + + + + + +No standard yetSocial interactions · feeding · facial expressions ·home-cage monitoring · VR · force plates + + diff --git a/figures/fig5_bbqs_stack/fig5_bbqs_stack.svgtune b/figures/fig5_bbqs_stack/fig5_bbqs_stack.svgtune new file mode 100644 index 0000000..9ecd914 --- /dev/null +++ b/figures/fig5_bbqs_stack/fig5_bbqs_stack.svgtune @@ -0,0 +1,55 @@ +# Walk through Fig. 5, one path to the archive at a time: NWB, BIDS, Psych-DS. +# Run: svgtune fig5_bbqs_stack.svgtune (https://github.com/yarikoptic/svgtune) +# -> fig5_bbqs_stack_tuned/.svg, in the order of %save below. +# Layers (steps) come from fig5_bbqs_stack.yaml; a step may have several +# layers (the z-order of the slide is kept), hence "label:re=^$". +%file fig5_bbqs_stack.svg + +# The stack: legend and empty layers 1-6 +layers style=display:none +layer label:re=^base$ style=display:inline +%save stack + +# BBQS data types at the bottom +layer label:re=^data$ style=display:inline +%save data + +# --- Path 1: NWB (orange) --- +# data formats: HDF5 / Zarr files, linked video +layer label:re=^nwb-format$ style=display:inline +%save nwb-format +# NWB files, their extensions, and HDMF which defines NWB +layer label:re=^nwb-file$ style=display:inline +%save nwb-file +# DANDI layout: one NWB file per subject and session +layer label:re=^nwb-dataset$ style=display:inline +%save nwb-dataset +# EMBER, with archive metadata in JSON Schema (Pydantic) +layer label:re=^archive$ style=display:inline +%save archive + +# --- Path 2: BIDS (green); NWB is dimmed --- +layer label:re=^nwb- style=opacity:0.3 +layer label:re=^bids-format$ style=display:inline +%save bids-format +# BIDS, its proposals (BEPs), the BIDS schema; NWB files in BIDS +layer label:re=^bids-dataset$ style=display:inline +%save bids-dataset +# companion proposals keep NWB and BIDS aligned (multi-subject) +layer label:re=^nwb-file$ style=opacity:1 +layer label:re=^companion$ style=display:inline +%save companion + +# --- Path 3: Psych-DS (slate); NWB and BIDS are dimmed --- +layer label:re=^(nwb-|bids-|companion$) style=opacity:0.3 +layer label:re=^psychds$ style=display:inline +%save psychds + +# Ontologies and terminologies serve both organization layers +layers style=opacity:1 +layer label:re=^ontologies$ style=display:inline +%save ontologies + +# What still needs a standard: the whole figure +layer label:re=^gaps$ style=display:inline +%save gaps diff --git a/figures/fig5_bbqs_stack/fig5_bbqs_stack.yaml b/figures/fig5_bbqs_stack/fig5_bbqs_stack.yaml new file mode 100644 index 0000000..dce7fde --- /dev/null +++ b/figures/fig5_bbqs_stack/fig5_bbqs_stack.yaml @@ -0,0 +1,101 @@ +# Links and build steps of Fig. 5 for tools/pptx2svg.py (run: make fig5). +# The .pptx is the editable source of the drawing; this file adds what +# PowerPoint does not keep well: a link for every element, and the Inkscape +# layers (steps) which fig5_bbqs_stack.svgtune shows one after another. +source: fig5_bbqs_stack_design.pptx +output: fig5_bbqs_stack.svg +title: "Fig. 5: The BBQS standards stack" + +# Shape name (regex) -> step; the first match wins, everything else is "base" +# (legend, layer rows and their titles). +steps: + - [gaps, '^Behavior labels$|^Data without a standard$'] + - [data, '^Data: |^Text 78$'] + - [nwb-format, '^(Bus|Feed|Join) A$|^HDF5 Zarr$|^Video formats$'] + - [nwb-file, '^NWB$|^NWB extension: |^HDMF$'] + - [nwb-dataset, '^DANDI layout$'] + - [archive, '^EMBER$|^JSON Schema'] + - [bids-format, '^(Bus|Feed|Join) B$|^NIfTI$|^EDF$|^JSON TSV$|^BIDS media$'] + - [bids-dataset, '^BIDS$|^BIDS BEP0|^BIDS schema$|^NWB in BIDS$|^Text 48$'] + - [companion, '^BIDS Multi-subject BEP$|^Companion proposals|^Text 58$'] + - [psychds, '^Path C$|^(Bus|Feed|Join) C$|^CSV JSON$|^Psych-DS$|^LinkML$'] + - [ontologies, '^HED$|^Neuro Termsets|^Terminology: '] + +# Long paths are cut where they enter a box, so each part shows with its step. +split: + 'Path A: data to NWB': {at: [449.3], steps: [nwb-format, nwb-file]} + 'Path A: NWB to EMBER': {at: [119.5], steps: [nwb-dataset, archive]} + 'Path B': {at: [449.3], steps: [bids-format, bids-dataset]} + +links: + # 5 archives + EMBER: https://emberarchive.org/ + # 3 dataset organization + DANDI layout: https://dandi.readthedocs.io/en/latest/cmdline/organize.html + BIDS: + _: https://bids-specification.readthedocs.io/en/stable/ + iEEG: https://bids-specification.readthedocs.io/en/stable/modality-specific-files/intracranial-electroencephalography.html + eye tracking: https://bids-specification.readthedocs.io/en/stable/modality-specific-files/physiological-recordings.html#eye-tracking + EMG: https://bids-specification.readthedocs.io/en/stable/modality-specific-files/electromyography.html + BIDS BEP032: https://bids.neuroimaging.io/extensions/beps/bep_032.html + BIDS BEP047: https://bids.neuroimaging.io/extensions/beps/bep_047.html + BIDS BEP044: https://bids.neuroimaging.io/extensions/beps/bep_044.html + BIDS Multi-subject BEP: https://github.com/bids-standard/bids-specification/issues/2512 + Psych-DS: https://psychds-docs.readthedocs.io/ + Text 48: # NWB files in BIDS + _: https://bids.neuroimaging.io/extensions/beps/bep_032.html + iEEG: https://bids-specification.readthedocs.io/en/stable/modality-specific-files/intracranial-electroencephalography.html + # 2 file organization + NWB: https://www.nwb.org/ + 'NWB extension: Pose estimation': https://github.com/rly/ndx-pose + 'NWB extension: Structured behavior': https://github.com/rly/ndx-structured-behavior + 'NWB extension: Microscopy': https://github.com/nwb-extensions/nwbep-review/tree/main/NWBEP004 + 'NWB extension: HED annotation': https://github.com/hed-standard/ndx-hed + 'NWB extension: Fiber photometry': https://github.com/catalystneuro/ndx-fiber-photometry + 'NWB extension: Wearable devices': https://github.com/BCM-Neurosurgery/ndx-wearables + 'NWB extension: Multi-subject': https://github.com/nehatk17/ndx-multisubjects + 'NWB extension: Ethogram': https://github.com/catalystneuro/ndx-ethogram + # 1 formats + HDF5 Zarr: + HDF5: https://www.hdfgroup.org/solutions/hdf5/ + Zarr: https://zarr.dev/ + Video formats: + MP4: https://www.loc.gov/preservation/digital/formats/fdd/fdd000155.shtml + AVI: https://www.loc.gov/preservation/digital/formats/fdd/fdd000059.shtml + MOV: https://developer.apple.com/documentation/quicktime-file-format + NIfTI: + NIfTI: https://nifti.nimh.nih.gov/nifti-1 + OME-Zarr: https://ngff.openmicroscopy.org/specifications/ + EDF: + EDF: https://www.edfplus.info/ + BrainVision: https://www.brainproducts.com/support-resources/brainvision-core-data-format-1-0/ + EMG: https://bids-specification.readthedocs.io/en/stable/modality-specific-files/electromyography.html + JSON TSV: + JSON: https://www.json.org/json-en.html + TSV: https://www.iana.org/assignments/media-types/text/tab-separated-values + BIDS media: https://github.com/bids-standard/bids-specification/pull/2367 + CSV JSON: + CSV: https://www.rfc-editor.org/info/rfc4180 + JSON: https://www.json.org/json-en.html + # 4 ontologies and terminologies + HED: https://www.hedtags.org/ + Neuro Termsets: https://github.com/NeurodataWithoutBorders/neuro-termsets + 'Terminology: NCBI Taxonomy': https://www.ncbi.nlm.nih.gov/taxonomy + 'Terminology: UBERON': https://obofoundry.org/ontology/uberon + 'Terminology: Allen atlases': https://atlas.brain-map.org/ + 'Terminology: RRID': https://www.rrids.org/ + 'Terminology: ORCID · ROR': + ORCID: https://orcid.org/ + ROR: https://ror.org/ + 'Terminology: Cell Ontology': https://obophenotype.github.io/cell-ontology/ + # 6 schema languages + HDMF: https://hdmf-schema-language.readthedocs.io/en/latest/ + BIDS schema: https://bids-specification.readthedocs.io/en/stable/appendices/schema.html + LinkML: https://linkml.io/ + JSON Schema (Pydantic): + _: https://github.com/dandi/dandi-schema + JSON Schema: https://json-schema.org/specification + Pydantic: https://pydantic.dev/docs/validation/latest/ + metadata: https://github.com/dandi/schema + # BBQS + Text 78: https://braininitiative.nih.gov/research/systems-neuroscience/brain-behavior-quantification-and-synchronization-program diff --git a/figures/fig5_bbqs_stack/fig5_bbqs_stack_design.png b/figures/fig5_bbqs_stack/fig5_bbqs_stack_design.png index 3274c9d..d9290ed 100644 Binary files a/figures/fig5_bbqs_stack/fig5_bbqs_stack_design.png and b/figures/fig5_bbqs_stack/fig5_bbqs_stack_design.png differ diff --git a/figures/fig5_bbqs_stack/fig5_bbqs_stack_design.pptx b/figures/fig5_bbqs_stack/fig5_bbqs_stack_design.pptx index 6bba556..0de4239 100644 Binary files a/figures/fig5_bbqs_stack/fig5_bbqs_stack_design.pptx and b/figures/fig5_bbqs_stack/fig5_bbqs_stack_design.pptx differ diff --git a/tools/pptx2svg.py b/tools/pptx2svg.py new file mode 100644 index 0000000..25e7c2c --- /dev/null +++ b/tools/pptx2svg.py @@ -0,0 +1,462 @@ +"""Convert a one-slide PowerPoint figure into a layered, hyperlinked SVG. + +Usage (from the paper root): + + python3 tools/pptx2svg.py figures/fig5_bbqs_stack/fig5_bbqs_stack.yaml + +The YAML file names the .pptx (``source``), the SVG to write (``output``), the +links of the shapes (``links``), and which build step (Inkscape layer) each +shape belongs to (``steps``), so that an svgtune file +(https://github.com/yarikoptic/svgtune) can walk through the figure. The +.pptx stays the editable source: re-run this after editing it. + +Supported: shapes with preset geometry rect, roundRect, ellipse and line +(straight, horizontal or vertical, optionally with an arrow at the end), solid +fills with alpha, solid or dashed outlines, and text boxes (Arial, bold, +italic, colour, left/centre alignment, top/centre anchoring, spacing after a +paragraph). Text is wrapped as PowerPoint does, using the metrics of Arial +or a metric-compatible font (Liberation Sans), and stays editable . +Anything else is reported and skipped. + +The configuration:: + + source: fig.pptx + output: fig.svg + links: # shape name -> URL, or phrase -> URL + EMBER: https://emberarchive.org + HDF5 Zarr: # links per word or phrase of the text + HDF5: https://www.hdfgroup.org/solutions/hdf5/ + Zarr: https://zarr.dev + _: https://... # optional: the rest of the shape + steps: # first matching regex (on shape name) wins + - [base, '^Layer '] + - [nwb, '^NWB'] + split: # cut a line into segments of other steps + Path B: {at: [449.3], steps: [bids-format, bids-dataset]} + +Each shape becomes ````; consecutive shapes of the +same step are wrapped in one Inkscape layer labelled with the step, so the +z-order of the slide is kept (a step can therefore have several layers; match +them with ``layer label:re=^$`` in svgtune). +""" + +from __future__ import annotations + +import re +import subprocess +import sys +import zipfile +from dataclasses import dataclass, field +from functools import lru_cache +from pathlib import Path +from xml.sax.saxutils import escape, quoteattr + +import yaml +from lxml import etree +from PIL import ImageFont + +NS = { + "a": "http://schemas.openxmlformats.org/drawingml/2006/main", + "p": "http://schemas.openxmlformats.org/presentationml/2006/main", +} +EMU_PT = 12700.0 +LINE_SPACING = 1.17 # PowerPoint single line spacing for Arial, in font sizes +ASCENT = 0.905 # Arial ascent, in font sizes +DASH = (4, 3) # PowerPoint "dash": dash and gap in line widths + + +def pt(v) -> float: + return int(v) / EMU_PT + + +def fmt(v: float) -> str: + return f"{v:.2f}".rstrip("0").rstrip(".") + + +@lru_cache(None) +def font(bold: bool, italic: bool) -> ImageFont.FreeTypeFont: + style = ":bold" * bold + ":italic" * italic + path = subprocess.run(["fc-match", "-f", "%{file}", "Arial" + style], + capture_output=True, text=True, check=True).stdout + return ImageFont.truetype(path, 100) + + +def text_width(s: str, size: float, bold: bool, italic: bool) -> float: + return font(bold, italic).getlength(s) * size / 100.0 + + +def slug(name: str) -> str: + s = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-") + return s if s and s[0].isalpha() else "s-" + s + + +@dataclass +class Run: + text: str + size: float + bold: bool + italic: bool + color: str + href: str | None = None + + +@dataclass +class Para: + runs: list[Run] + align: str + space_after: float + + +@dataclass +class Shape: + name: str + geom: str + x: float + y: float + w: float + h: float + flip_h: bool = False + flip_v: bool = False + adj: float | None = None + fill: str | None = None + fill_opacity: float = 1.0 + stroke: str | None = None + stroke_width: float = 0.0 + dashed: bool = False + arrow_end: bool = False + paras: list[Para] = field(default_factory=list) + insets: tuple = (7.2, 3.6, 7.2, 3.6) # l, t, r, b + anchor: str = "t" + wrap: bool = True + + +def color_of(el) -> tuple[str | None, float]: + if el is None or el.find("a:noFill", NS) is not None: + return None, 1.0 + c = el.find("a:solidFill/a:srgbClr", NS) + if c is None: + return None, 1.0 + alpha = c.find("a:alpha", NS) + return "#" + c.get("val"), (int(alpha.get("val")) / 1e5 if alpha is not None else 1.0) + + +def parse_shape(sp, warn) -> Shape | None: + name = sp.find(".//p:cNvPr", NS).get("name") + sppr = sp.find("p:spPr", NS) + xfrm = sppr.find("a:xfrm", NS) + geom = sppr.find("a:prstGeom", NS) + if xfrm is None or geom is None: + warn(f"{name!r}: no position or preset geometry, skipped") + return None + off, ext = xfrm.find("a:off", NS), xfrm.find("a:ext", NS) + shp = Shape(name, geom.get("prst"), pt(off.get("x")), pt(off.get("y")), + pt(ext.get("cx")), pt(ext.get("cy")), + xfrm.get("flipH") == "1", xfrm.get("flipV") == "1") + if shp.geom not in ("rect", "roundRect", "ellipse", "line"): + warn(f"{name!r}: geometry {shp.geom} not supported, skipped") + return None + gd = geom.find("a:avLst/a:gd", NS) + if gd is not None: + shp.adj = int(gd.get("fmla").split()[1]) / 1e5 + shp.fill, shp.fill_opacity = color_of(sppr) + ln = sppr.find("a:ln", NS) + if ln is not None: + shp.stroke, _ = color_of(ln) + shp.stroke_width = pt(ln.get("w", 12700)) + dash = ln.find("a:prstDash", NS) + shp.dashed = dash is not None and dash.get("val") != "solid" + tail = ln.find("a:tailEnd", NS) + shp.arrow_end = tail is not None and tail.get("type", "none") != "none" + if ln.find("a:headEnd", NS) is not None: + warn(f"{name!r}: arrow heads at the start are not supported") + body = sp.find("p:txBody", NS) + if body is not None: + bp = body.find("a:bodyPr", NS) + shp.insets = tuple(pt(bp.get(k, d)) for k, d in + (("lIns", 91440), ("tIns", 45720), ("rIns", 91440), ("bIns", 45720))) + shp.anchor = bp.get("anchor", "t") + shp.wrap = bp.get("wrap", "square") != "none" + for p in body.findall("a:p", NS): + ppr = p.find("a:pPr", NS) + align = ppr.get("algn", "l") if ppr is not None else "l" + spc = p.find("a:pPr/a:spcAft/a:spcPts", NS) + runs = [] + for r in p.findall("a:r", NS): + rpr = r.find("a:rPr", NS) + col, _ = color_of(rpr) + runs.append(Run(r.findtext("a:t", "", NS), int(rpr.get("sz", 1800)) / 100, + rpr.get("b") == "1", rpr.get("i") == "1", col or "#000000")) + if runs: + shp.paras.append(Para(runs, align, int(spc.get("val")) / 100 if spc is not None else 0)) + return shp + + +# --------------------------------------------------------------- links +def assign_links(shp: Shape, spec) -> str | None: + """Give each run (split into words) its href; return the shape's default href.""" + if spec is None: + default, phrases = None, {} + elif isinstance(spec, str): + default, phrases = spec, {} + else: + default = spec.get("_") + phrases = {k: v for k, v in spec.items() if k != "_"} + used = set() + for para in shp.paras: + words: list[Run] = [] + for r in para.runs: + for tok in re.split(r"( +)", r.text): + if tok: + words.append(Run(tok, r.size, r.bold, r.italic, r.color, default)) + for phrase, href in phrases.items(): + parts = phrase.split() + nonspace = [i for i, w in enumerate(words) if not w.text.isspace()] + for k in range(len(nonspace) - len(parts) + 1): + idx = nonspace[k:k + len(parts)] + if [words[i].text.strip(".,;:()") for i in idx] == parts: + for i in range(idx[0], idx[-1] + 1): + words[i].href = href + used.add(phrase) + para.runs = words + missing = set(phrases) - used + if missing: + raise SystemExit(f"{shp.name!r}: link phrases not found in its text: {sorted(missing)}") + return default + + +# --------------------------------------------------------------- text +def layout(para: Para, width: float, wrap: bool) -> list[list[Run]]: + """Break the runs (words and spaces) of a paragraph into lines.""" + lines, cur, cur_w = [], [], 0.0 + for r in para.runs: + w = text_width(r.text, r.size, r.bold, r.italic) + if r.text.isspace(): + if cur: + cur.append(r) + cur_w += w + continue + if wrap and cur and cur_w + w > width + 0.01: + while cur and cur[-1].text.isspace(): + cur.pop() + lines.append(cur) + cur, cur_w = [], 0.0 + cur.append(r) + cur_w += w + while cur and cur[-1].text.isspace(): + cur.pop() + if cur: + lines.append(cur) + return lines + + +def text_svg(shp: Shape) -> str: + l, t, r, b = shp.insets + box_w = shp.w - l - r + blocks = [] # (para, lines) + total = 0.0 + for para in shp.paras: + lines = layout(para, box_w, shp.wrap) + size = max((x.size for x in para.runs), default=10) + blocks.append((para, lines, size)) + total += len(lines) * size * LINE_SPACING + para.space_after + if blocks: + total -= blocks[-1][0].space_after + if shp.anchor == "ctr": + y = shp.y + t + (shp.h - t - b - total) / 2 + elif shp.anchor == "b": + y = shp.y + shp.h - b - total + else: + y = shp.y + t + out = [] + for para, lines, size in blocks: + for line in lines: + base = y + size * (LINE_SPACING - 1) / 2 + size * ASCENT + if para.align == "ctr": + x, anchor = shp.x + l + box_w / 2, "middle" + elif para.align == "r": + x, anchor = shp.x + shp.w - r, "end" + else: + x, anchor = shp.x + l, "start" + # merge neighbouring words of one style and link + groups: list[list[Run]] = [] + for w in line: + if groups and (groups[-1][0].size, groups[-1][0].bold, groups[-1][0].italic, + groups[-1][0].color, groups[-1][0].href) == ( + w.size, w.bold, w.italic, w.color, w.href): + groups[-1].append(w) + else: + groups.append([w]) + spans = [] + for g in groups: + r0 = g[0] + attrs = f' font-size="{fmt(r0.size)}" fill="{r0.color}"' + if r0.bold: + attrs += ' font-weight="bold"' + if r0.italic: + attrs += ' font-style="italic"' + span = f"{escape(''.join(w.text for w in g))}" + if r0.href: + span = f'{span}' + spans.append(span) + out.append(f'{"".join(spans)}') + y += size * LINE_SPACING + y += para.space_after + return "".join(out) + + +# --------------------------------------------------------------- shapes +def marker_id(color: str) -> str: + return "arrow-" + color.lstrip("#").lower() + + +def line_ends(shp: Shape) -> tuple[float, float, float, float]: + x1, y1, x2, y2 = shp.x, shp.y, shp.x + shp.w, shp.y + shp.h + if shp.flip_h: + x1, x2 = x2, x1 + if shp.flip_v: + y1, y2 = y2, y1 + return x1, y1, x2, y2 + + +def stroke_attrs(shp: Shape) -> str: + if not shp.stroke: + return ' stroke="none"' + s = f' stroke="{shp.stroke}" stroke-width="{fmt(shp.stroke_width)}"' + if shp.dashed: + s += f' stroke-dasharray="{fmt(DASH[0] * shp.stroke_width)},{fmt(DASH[1] * shp.stroke_width)}"' + return s + + +def segment_svg(shp: Shape, x1, y1, x2, y2, arrow: bool) -> str: + extra = "" + if arrow: + # the marker tip is at the end point: shorten the line under the arrow head + import math + d = math.hypot(x2 - x1, y2 - y1) + k = 2.5 * shp.stroke_width / d if d else 0 + x2, y2 = x2 - (x2 - x1) * k, y2 - (y2 - y1) * k + extra = f' marker-end="url(#{marker_id(shp.stroke)})"' + return (f'') + + +def shape_svg(shp: Shape, default_href: str | None) -> str: + if shp.geom == "line": + return segment_svg(shp, *line_ends(shp), shp.arrow_end) + fill = f' fill="{shp.fill}"' if shp.fill else ' fill="none"' + if shp.fill and shp.fill_opacity < 1: + fill += f' fill-opacity="{fmt(shp.fill_opacity)}"' + common = fill + stroke_attrs(shp) + if shp.geom == "ellipse": + el = (f'') + else: + rx = "" + if shp.geom == "roundRect": + rad = min(shp.w, shp.h) * (0.16667 if shp.adj is None else shp.adj) + rx = f' rx="{fmt(rad)}"' + el = (f'') + if default_href and (shp.fill or shp.stroke): + el = f'{el}' + return el + text_svg(shp) + + +def main(cfg_path: str) -> None: + cfg_file = Path(cfg_path) + cfg = yaml.safe_load(cfg_file.read_text()) + here = cfg_file.parent + src, out = here / cfg["source"], here / cfg["output"] + links = cfg.get("links", {}) + steps = [(name, re.compile(rx)) for name, rx in cfg.get("steps", [])] + splits = cfg.get("split", {}) + + def warn(msg): + print("WARNING:", msg, file=sys.stderr) + + with zipfile.ZipFile(src) as z: + pres = etree.fromstring(z.read("ppt/presentation.xml")) + sld = etree.fromstring(z.read("ppt/slides/slide1.xml")) + size = pres.find("p:sldSz", NS) + W, H = pt(size.get("cx")), pt(size.get("cy")) + + items = [] # (step, svg) + seen_ids: dict[str, int] = {} + unused_links = set(links) + colors = set() + for el in sld.find("p:cSld/p:spTree", NS): + tag = etree.QName(el).localname + if tag in ("nvGrpSpPr", "grpSpPr"): + continue + if tag != "sp": + warn(f"element <{tag}> not supported, skipped") + continue + shp = parse_shape(el, warn) + if shp is None: + continue + sid = slug(shp.name) + seen_ids[sid] = seen_ids.get(sid, 0) + 1 + if seen_ids[sid] > 1: + sid += f"-{seen_ids[sid]}" + step = next((n for n, rx in steps if rx.search(shp.name)), "base") + unused_links.discard(shp.name) + href = assign_links(shp, links.get(shp.name)) + label = quoteattr(shp.name) + if shp.arrow_end and shp.stroke: + colors.add(shp.stroke) + if shp.name in splits and shp.geom == "line": + sp = splits.pop(shp.name) + x1, y1, x2, y2 = line_ends(shp) + # cut points along the line, in order from its start to its end + cuts = sorted(sp["at"], key=lambda c: abs(c - (y1 if x1 == x2 else x1))) + pts = [(x1, y1)] + [((x1, c) if x1 == x2 else (c, y1)) for c in cuts] + [(x2, y2)] + assert len(sp["steps"]) == len(pts) - 1, shp.name + for i, st in enumerate(sp["steps"]): + last = i == len(pts) - 2 + body = segment_svg(shp, *pts[i], *pts[i + 1], shp.arrow_end and last) + items.append((st, f'{body}')) + continue + items.append((step, f'{shape_svg(shp, href)}')) + if unused_links: + raise SystemExit(f"links for shapes not in the slide: {sorted(unused_links)}") + if splits: + raise SystemExit(f"split for lines not in the slide: {sorted(splits)}") + + defs = "".join( + f'' + f'' for c in sorted(colors)) + layers, counts = [], {} + for step, svg in items: + if layers and layers[-1][0] == step: + layers[-1][1].append(svg) + else: + layers.append((step, [svg])) + body = [] + for step, svgs in layers: + counts[step] = counts.get(step, 0) + 1 + lid = f"layer-{slug(step)}" + (f"-{counts[step]}" if counts[step] > 1 else "") + body.append(f'\n' + "\n".join(svgs) + "\n") + title = escape(cfg.get("title", src.stem)) + svg = ( + '\n' + f'\n' + f'\n' + f"{title}\n{defs}\n" + f'\n' + + "\n".join(body) + "\n\n") + out.write_text(svg) + n_links = svg.count("