supertensor: shape-aware tensor figure toolkit
Extracted from the tensor-formula-viz skill and rebuilt around the idea that the geometry rules should be enforced by construction rather than restated as prose an agent has to remember. - assets/supertensor.sty: faces, stacks, index faces, shared caption lanes, meaning box, signature. Macros take a declared axis and a declared role, so equal shapes get equal edges, a x a is square, a transpose swaps the face, and contracted axes share an edge length -- without any manual alignment. - scripts/preflight.sh: decide the TikZ/CJK path before drawing. - scripts/build.sh: compile and fail on silent corruption (missing CJK glyphs, overfull boxes, undeclared roles), then export pdf/svg/png/thumb. - scripts/test.sh: build every figure as a regression test for the package. - examples/: three golden figures (TP-FFN, causal MHA, MoE top-k gather) plus an anti-pattern gallery of figures that compile cleanly and still lie. - SKILL.md + references/: lean entry point, details loaded on demand.
This commit is contained in:
dela
Executable
+74
@@ -0,0 +1,74 @@
|
||||
#!/usr/bin/env bash
|
||||
# Compile a supertensor figure and export every delivery artifact.
|
||||
#
|
||||
# ./scripts/build.sh figure.tex [outdir]
|
||||
#
|
||||
# Produces in outdir (default: alongside the source, in build/):
|
||||
# figure.pdf vector master
|
||||
# figure.svg vector, for slides/web
|
||||
# figure.png white background, 300 dpi <- inspect this one
|
||||
# figure-alpha.png transparent background
|
||||
# figure-thumb.png 360 px wide <- inspect this for the color/hue audit
|
||||
#
|
||||
# The build FAILS on silent-corruption signals, not only on TeX errors:
|
||||
# missing CJK glyphs and overfull boxes both produce figures that compile
|
||||
# happily and read wrong.
|
||||
set -euo pipefail
|
||||
|
||||
SRC="${1:?usage: build.sh figure.tex [outdir]}"
|
||||
[[ -f "$SRC" ]] || { echo "no such file: $SRC" >&2; exit 2; }
|
||||
SRCDIR="$(cd "$(dirname "$SRC")" && pwd)"
|
||||
BASE="$(basename "$SRC" .tex)"
|
||||
OUT="${2:-$SRCDIR/build}"
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
mkdir -p "$OUT"
|
||||
|
||||
echo "==> xelatex $BASE"
|
||||
# supertensor.sty lives in assets/; keep it off the user's texmf tree.
|
||||
TEXINPUTS="$ROOT/assets:$SRCDIR:" \
|
||||
xelatex -halt-on-error -interaction=nonstopmode \
|
||||
-output-directory="$OUT" "$SRC" >/dev/null 2>&1 \
|
||||
|| { echo "!! xelatex failed; last errors:" >&2
|
||||
grep -n -A4 -m3 '^!' "$OUT/$BASE.log" >&2 || tail -30 "$OUT/$BASE.log" >&2
|
||||
exit 1; }
|
||||
|
||||
LOG="$OUT/$BASE.log"
|
||||
status=0
|
||||
|
||||
if grep -q "Missing character" "$LOG"; then
|
||||
echo "!! missing glyphs (CJK font not applied?):" >&2
|
||||
grep -m5 "Missing character" "$LOG" >&2
|
||||
status=1
|
||||
fi
|
||||
if grep -qE "^(Overfull|Underfull) \\\\[hv]box" "$LOG"; then
|
||||
echo "!! overfull/underfull boxes -- text is escaping its reserved lane:" >&2
|
||||
grep -m5 -E "^(Overfull|Underfull) \\\\[hv]box" "$LOG" >&2
|
||||
status=1
|
||||
fi
|
||||
if grep -q "Package supertensor Warning" "$LOG"; then
|
||||
echo "!! supertensor warnings:" >&2
|
||||
grep -m5 -A2 "Package supertensor Warning" "$LOG" >&2
|
||||
status=1
|
||||
fi
|
||||
|
||||
if command -v pdftocairo >/dev/null 2>&1; then
|
||||
echo "==> exporting svg / png"
|
||||
pdftocairo -svg "$OUT/$BASE.pdf" "$OUT/$BASE.svg"
|
||||
pdftocairo -png -r 300 -singlefile "$OUT/$BASE.pdf" "$OUT/$BASE"
|
||||
pdftocairo -png -r 300 -singlefile -transp "$OUT/$BASE.pdf" "$OUT/$BASE-alpha"
|
||||
pdftocairo -png -scale-to-x 360 -scale-to-y -1 -singlefile \
|
||||
"$OUT/$BASE.pdf" "$OUT/$BASE-thumb"
|
||||
else
|
||||
echo "!! pdftocairo missing: PDF only, no SVG/PNG" >&2
|
||||
status=1
|
||||
fi
|
||||
|
||||
echo "==> artifacts in $OUT"
|
||||
ls -1 "$OUT/$BASE"*.{pdf,svg,png} 2>/dev/null | sed 's/^/ /'
|
||||
if [[ $status -ne 0 ]]; then
|
||||
echo "==> BUILD DIRTY: fix the warnings above before delivering." >&2
|
||||
else
|
||||
echo "==> clean. Now do the visual audit (references/checklist.md) --"
|
||||
echo " a clean build says nothing about collisions or hue budget."
|
||||
fi
|
||||
exit $status
|
||||
Executable
+54
@@ -0,0 +1,54 @@
|
||||
#!/usr/bin/env bash
|
||||
# Toolchain preflight for supertensor. Run this BEFORE drawing anything:
|
||||
# it decides whether the TikZ path is available or the figure must fall back.
|
||||
#
|
||||
# ./scripts/preflight.sh human-readable report
|
||||
# ./scripts/preflight.sh --quiet exit code only (0 = full TikZ path OK)
|
||||
#
|
||||
# Exit codes: 0 full path, 1 degraded (no CJK), 2 no LaTeX at all.
|
||||
set -uo pipefail
|
||||
|
||||
QUIET=0
|
||||
[[ "${1:-}" == "--quiet" ]] && QUIET=1
|
||||
say() { [[ $QUIET -eq 1 ]] || echo -e "$*"; }
|
||||
|
||||
ok=0; warn=0; fail=0
|
||||
check() { # name, command
|
||||
local name="$1"; shift
|
||||
if "$@" >/dev/null 2>&1; then say " ok $name"; ok=$((ok+1)); return 0
|
||||
else say " MISS $name"; return 1; fi
|
||||
}
|
||||
|
||||
say "supertensor preflight"
|
||||
say "--- required ---"
|
||||
check "xelatex" command -v xelatex || fail=$((fail+1))
|
||||
check "standalone.cls" kpsewhich standalone.cls || fail=$((fail+1))
|
||||
check "tikz.sty" kpsewhich tikz.sty || fail=$((fail+1))
|
||||
check "xstring.sty" kpsewhich xstring.sty || fail=$((fail+1))
|
||||
|
||||
say "--- chinese figures ---"
|
||||
check "ctex.sty" kpsewhich ctex.sty || warn=$((warn+1))
|
||||
check "fandol font" kpsewhich FandolSong-Regular.otf || warn=$((warn+1))
|
||||
|
||||
say "--- raster / vector export ---"
|
||||
check "pdftocairo" command -v pdftocairo || warn=$((warn+1))
|
||||
check "latexmk (optional)" command -v latexmk || true
|
||||
|
||||
if [[ $fail -gt 0 ]]; then
|
||||
say ""
|
||||
say "RESULT: no usable LaTeX path."
|
||||
say "Fall back to an SVG or matplotlib figure and say so explicitly in the"
|
||||
say "delivery; do not silently ship a lower-fidelity figure as if it were TikZ."
|
||||
exit 2
|
||||
fi
|
||||
if [[ $warn -gt 0 ]]; then
|
||||
say ""
|
||||
say "RESULT: degraded."
|
||||
say " - missing ctex/fandol -> English-label figures only; do not substitute"
|
||||
say " an OS-specific CJK font without telling the user it costs portability."
|
||||
say " - missing pdftocairo -> deliver PDF only, and say PNG/SVG were skipped."
|
||||
exit 1
|
||||
fi
|
||||
say ""
|
||||
say "RESULT: full path available (TikZ + CJK + vector/raster export)."
|
||||
exit 0
|
||||
Executable
+28
@@ -0,0 +1,28 @@
|
||||
#!/usr/bin/env bash
|
||||
# Build every example and the smoke test. Any dirty build fails the run.
|
||||
#
|
||||
# ./scripts/test.sh
|
||||
#
|
||||
# This is a regression test for assets/supertensor.sty: the examples exercise
|
||||
# faces, stacks, index faces, every pattern, shared caption lanes, connectors,
|
||||
# the meaning box and the signature.
|
||||
set -uo pipefail
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
fail=0
|
||||
|
||||
for f in "$ROOT"/tests/*.tex "$ROOT"/examples/*.tex; do
|
||||
[[ -e "$f" ]] || continue
|
||||
name="$(basename "$f")"
|
||||
if "$ROOT/scripts/build.sh" "$f" >/dev/null 2>&1; then
|
||||
echo " ok $name"
|
||||
else
|
||||
echo " FAIL $name"
|
||||
fail=$((fail+1))
|
||||
fi
|
||||
done
|
||||
|
||||
if [[ $fail -gt 0 ]]; then
|
||||
echo "$fail failing figure(s); rerun scripts/build.sh on one to see why" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "all figures build clean"
|
||||
Reference in New Issue
Block a user