CANONICAL(1)

💖 NAME 💖

okay bestie, welcome to the canonical(1) page. The command is canonical, and its whole job is to canonicalize a polyhedon — yes, “polyhedon” exactly like that, iykyk 😌💅

🦋 SYNOPSIS 🦋

canonical [options] [input_file]

💅 DESCRIPTION 💅

So canonical reads a polyhedron from a file in OFF format. Then it canonicalizes or planarizes it. ✨ It uses algorithms by George W. Hart, and the page gives these links: http://www.georgehart.com/, http://www.georgehart.com/virtual-polyhedra/conway_notation.html, and http://www.georgehart.com/virtual-polyhedra/canonical.html. If input_file is not given, the program reads from standard input. no cap 🫶

✨ Options ✨

• -h, --help — this help message (run off_util -H help for general help). 💖
• --version — version information.
• -H — documentation on algorithm.
• -z <nums> — number of iterations between status reports (implies termination check) (0 for final report only, -1 for no report), optionally followed by a comma and the number of iterations between termination checks (0 for report checks only) (default: 1000,1).
• -l <lim> — minimum distance change to terminate, as negative exponent (default: 12 giving 1e-12).

⚠️ WARNING: high values can cause non-terminal behaviour. Use -n.

• -o <file> — write output to file (default: write to standard output).

🎀 Canonical and Planarization Options 🎀

• -e <opt> — edge distribution (default: none, canonicalization only). s - project vertices onto a sphere.
• -s <opt> — shuffle model indexes. v - vertices, e - edges, f - faces, a - all (default: none).
• -t <opt> — target model. b - work on base only (default), p - work on dual for planarization only, c - work on dual for planarization and canonicalization.
• -p <opt> — planarization only, or initial planarization if -c is set (default: no planarization). p - poly_form planarize (poly_form -a p), m - mathematica planarize, a - moving edge planarize, b - base/dual (reciprocate on face centroids magnitude squared).
• -i <itrs> — maximum planarize iterations. -1 for unlimited (default: -1).

😭 WARNING: unstable models may not finish unless -i is set.

• -c <opt> — canonicalization. c - circle packings (default), m - mathematica version, a - moving edge version, b - base/dual version (reciprocate on face normals), x - none (default, if -p is set).
• -n <itrs> — maximum canonical iterations. -1 for unlimited (default: -1).

💀 WARNING: unstable models may not finish unless -n is set.

• -d <perc> — radius test. percent difference between minimum and maximum radius; checks if polyhedron is collapsing. 0 for no test (default: 80 for canonicalizing, not used for planarizing).
• -y — maintain symmetry and alignment of the base model during processing (with -p p, -c c).

💖 Extra Options 💖

• -Q <perc> — percentage to scale edge tangency (default: 50) (-c m).
• -P <perc> — percentage to scale face planarity (default: 20) (-c m, -p m, -p p).
• -f <adj> — initial percent adjustment factor, optionally followed by a comma and a maximum percent adjustment (default: 1,50) (-c c).
• -C — continue processing a near-canonical model (the initial intermediate processing model will preserve the geometry of the base model rather than avoid scrambling) (-c c).

🌈 Scene Options 🌈

• -O <args> — output b - base, d - dual, i - intersection points (default: b); edge nearpoints, n - base, m - dual; c - base/dual convex hull edge nearpoints centroid, p - base, q - dual; o - origin point tangent sphere, u - minimum, U - maximum incircles, s - base, t - dual; as rings, S - base, T - dual.
• -q <dist> — incircles offset to avoid coplanarity e.g 0.0001 (default: 0).
• -g <opt> — roundness of tangent sphere, positive integer n (default: 8).
• -Y — align output model geometry to full symmetry.

🍓 Coloring Options 🍓

Coloring Options (run off_util -H color for help on color formats). keyword: none - sets no color, u - input base model, color of element unchanged. 🎨

• -F <col> — face color/operation, assignment (required), transparency (optional). The assignment targets are: b - base, d - dual, i - intersection points edge nearpoints, n - base, m - dual; c - base/dual convex hull edge nearpoints centroid, p - base, q - dual; o - origin point, u - tangent sphere, incircles (or rings), s - base, t - dual (one element, required; multiple -F as needed). -F d,b - face color by convexity, -F b,d - color from base verts; -F s,f take color from faces, -F t,f take color from faces. defaults: b - 'u' unchanged, d - 'b' take color from base verts, i - yellow, n,p - red, m,q - darkgreen, c - white, o - yellow, u - white, s,t - 'f' color of face.
• -E <col> — edge color (same format as for faces) (defaults: unchanged). -E d,b - edge color by convexity.
• -V <col> — vertex color (same format as for faces) (defaults: unchanged). transparency: valid range from 0 (invisible) to 255 (opaque).
• -m <maps> — a comma separated list of color maps used to transform color indexes (default: colorful), a part consisting of letters from v, e, f, selects the element types to apply the map list to (default 'vef'). use map name of 'index' to output index numbers.

🎨 convexity 🎨

white,gray50,gray25 (for -F d,b, -E d,b).

👑 SEE ALSO 👑

The full documentation for canonical is maintained as a Texinfo manual. If the info and canonical programs are properly installed at your site, the command

info canonical

should give you access to the complete manual.

---

💋 signed, sealed, slayed: this is canonical from Antiprism 0.32 over at http://..., and the footer tag is CANONICAL(1). mwah 🫶✨