Skip to content

Turn the notebook into a walk-through of the method; render the math - #77

Merged
joeljose merged 1 commit into
mainfrom
docs/notebook-walkthrough
Sep 29, 2026
Merged

joeljose merged 1 commit into
mainfrom
docs/notebook-walkthrough

Conversation

@joeljose

Copy link
Copy Markdown
Owner

Closes #76

Notebook

It now mirrors docs/theory.md (20 cells, about 1,000 words of explanation, up from about 340), with runnable experiments on face.mp4:

  1. Setup and input.
  2. DTCWT sub-bands of a frame.
  3. Phase against sub-pixel shift per level. It prints the slope, wavelength and half-turn shift: 4.1 / 6.0 / 11.2 / 19.6 / 43.3 px wavelengths.
  4. One coefficient's phase over time, with its baseline and detail.
  5. The width-mode gain G(f) against band mode. It prints the 0.20–8.59 Hz band and the 0.1 Hz resolution.
  6. The full magnification, with switches for color_space and band_hz.
  7. Before/after comparison.
  8. The displacement limit on a synthetic ring: 2 px gives 0.95k with 1.7% ghost energy; 8 px gives 0.61k with 27.4%.

Executed top to bottom with jupyter nbconvert --execute in a fresh python:3.12-slim container with NumPy 2 preinstalled, as on Colab. There were no errors, all six figures rendered, and face_k3.avi was written.

Math rendering

  • docs/theory.md and the notebook now use LaTeX ($...$, $$...$$) instead of plain-text formulas, so GitHub, Jupyter and Colab typeset them.
  • Checked with GitHub's own Markdown API (POST /markdown): all 61 expressions in theory.md and all 26 in the README come back as math, unchanged. The 4 other $...$ matches in the README are shell code ($(id -u)) and correctly stay code.
  • Two GitHub pitfalls found and avoided:
    • \, (thin space) loses its backslash, because Markdown treats it as an escape.
    • < gets double-escaped inside math and would show as &lt;, so it's written as \lt.

README notebook description and CHANGELOG updated.

The notebook had one explanatory paragraph per step. It now follows
docs/theory.md with small experiments on face.mp4: the DTCWT sub-bands,
phase against a sub-pixel shift per level (with the wrap-around limit),
one coefficient's phase through the temporal filter, the filter's gain
against frequency, the full magnification (rgb or yiq, width or band
mode), before and after, and the displacement limit on a synthetic ring.

Equations in docs/theory.md and the notebook are now LaTeX ($...$,
$$...$$), which GitHub, Jupyter and Colab render. Thin spaces (\,) are
avoided because GitHub's Markdown parser strips the backslash, and
"<" is written as \lt because GitHub double-escapes it inside math.

Closes #76
@joeljose
joeljose merged commit 333a2a2 into main Sep 29, 2026
2 checks passed
@joeljose
joeljose deleted the docs/notebook-walkthrough branch September 29, 2026 07:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Notebook: follow docs/theory.md with small runnable experiments

1 participant