Ole-Morten Duesund f8b7ff475c Initial commit: business card raytracer with explanation

Preserves Andrew Kensler's original card.cc verbatim and adds:
- CMakeLists.txt building both the original and a de-obfuscated
  variant (card_explained.cc) that produces a visually identical render
- A heavily annotated rewrite explaining the vector ops, ray-sphere
  intersection, soft shadows, depth of field, and reflection recursion
- Rendered sample output (docs/aek.png) embedded in the README
- CLAUDE.md establishing the "never modify card.cc" rule for future work

2026-05-28 13:47:50 +02:00

2.1 KiB

Raw Blame History

card-raytracer — project notes for Claude

This repo is a small study of Andrew Kensler's "business card raytracer". The point of the project is preservation + explanation, not extension.

The sacred rule

card.cc must never be modified. It is a historical artifact, ~1337 characters of obfuscated C++ that fits on a real business card. Any cleanup, formatting, comment, or "fix" goes into card_explained.cc instead.

If a compiler warning or modern-C++ issue appears against card.cc, the answer is always a CMake flag adjustment (e.g. silencing warnings), never an edit to the source.

Layout

File	Role
`card.cc`	Original, golfed, untouched. Read-only by convention.
`card_explained.cc`	De-obfuscated rewrite with full names and comments. Same visual output.
`CMakeLists.txt`	Builds both binaries; provides `image` and `image_explained` render targets.
`docs/aek.png`	Published render used by the README. Regenerate after meaningful changes.
`README.md`	Human-facing description with the embedded render.

Build & render

cmake -S . -B build
cmake --build build                          # builds both binaries
cmake --build build --target image           # → build/aek.ppm
cmake --build build --target image_explained # → build/aek_explained.ppm

Convert PPM → PNG (for README, etc.) with pnmtopng build/aek.ppm > docs/aek.png.

Conventions

card_explained.cc is built with -Wall -Wextra and should stay warning-clean. card.cc is built with -w because we can't edit it.
C++14, no external dependencies beyond libm.
The de-obfuscated version preserves the same rand() call sequence as the original so the rendered image is visually identical. Don't reorder the randf() calls inside shade() or the per-sample loop in main() without re-checking the output.

Remote

Hosted on Forgejo: ssh://git@kode.naiv.no:2222/olemd/card-raytracer.git. Per global instructions, use the forgejo skill (invoke via /forgejo) and the fj CLI for any repository interactions (PRs, issues, releases, etc.). Never use gh for this repo.

2.1 KiB Raw Blame History