Fractal manipulation with LLMs

These details have not been verified by PyPI

Project links

Project description

tranZoom

Fractal manipulation with LLMs

Primary use case: Render ultra-deep Mandelbrot Set and Julia Set fractal images with arbitrary precision and use AI/LLMs to guide fractal zoom sequences
Works with: Local filesystem (PNG output), complex-plane coordinates, local LLM vision models (via LMStudio + transai)
Status: Early / experimental — core fractal engine is functional; AI-guided zoom is functional
License: Apache-2.0

tranZoom is a Python CLI tool for rendering the Mandelbrot set and Julia Sets at virtually unlimited zoom depth using arbitrary-precision arithmetic (gmpy2), and for navigating fractals using AI. The goal is to be able to zoom so deep that standard double-precision floating point becomes meaningless — tranZoom automatically computes the required precision and renders faithfully at any scale. The tranz zoom ai command uses local LLM vision models (via transai / LMStudio) to evaluate each rendered frame, score nine sectors for visual interest, and autonomously navigate toward the most promising region of the fractal.

Since version 1.0.0 it is a PyPI package: https://pypi.org/project/tranzoom/

Built with:

Python 3.12+ with Poetry for dependency management
gmpy2 for arbitrary-precision (mpq/mpfr) complex-plane arithmetic
Pillow for PNG image output
imageio + imageio-ffmpeg + numpy for GIF and MP4 animation export
tqdm for progress bars during rendering
transai for AI/LLM integration (LMStudio vision models)
Typer + Rich for the CLI and terminal output
Transcrypto for CLI boilerplate, logging, hashing, and config management
Ruff, MyPy, Pyright, typeguard, pre-commit, GitHub Actions for quality and CI

tranZoom

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License here.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Third-party notices

This project includes or depends on third-party software (see requirements.txt and pyproject.toml). Key dependencies include:

gmpy2 — Apache-2.0 compatible
Pillow — HPND license
tqdm — MPL-2.0 / MIT
pydantic — MIT
transai — Apache-2.0
transcrypto — Apache-2.0

Contributions and inbound licensing

Contributions are accepted under the Apache-2.0 license (same as project).

Installation

To install from PyPI:

pip3 install tranzoom

Or install from the repository for development (see Development Setup).

Supported platforms

OS: Linux, macOS
Architectures: x86_64, arm64
Python: 3.12, 3.13, 3.14

Known dependencies (Prerequisites)

python 3.12+ — documentation
gmpy2 2.3+ — Arbitrary-precision arithmetic using GMP/MPFR/MPC — documentation
Pillow 12.2+ — PNG image generation — documentation
imageio 2.37+ — GIF and image sequence I/O — documentation
imageio-ffmpeg 0.6+ — MP4 video export via FFmpeg — documentation
numpy 2.4+ — Array operations for animation frame conversion — documentation
tqdm 4.67+ — Progress bars — documentation
rich 15.0+ — Terminal formatting — documentation
typer 0.25+ — CLI parser — documentation
transai 1.3+ — AI/LLM integration (LMStudio vision models) — documentation
transcrypto 2.6.1+ — CLI utilities, logging, hashing, config — documentation

Context / Problem Space

What this tool is

tranZoom is a command-line fractal renderer focused on extreme zoom depth for Mandelbrot Set and Julia Set. Standard double-precision (float64) floating point has only about 15–16 significant decimal digits, so any zoom below roughly 1e-14 of the full Mandelbrot set will produce incorrect images due to precision loss. tranZoom uses gmpy2.mpq (exact rational arithmetic) to represent frame coordinates and gmpy2.mpfr (arbitrary-precision floating point) for the escape-time computations, automatically determining how many bits of precision are needed for any given zoom level. Starting with version 1.3.0, tranZoom also renders Julia Sets — the same arbitrary-precision engine works for any complex-constant Julia iteration.

Starting with version 1.1.0, tranZoom can use local LLM vision models to autonomously guide the zoom — identifying visually interesting regions, scoring nine sectors of the current frame, and navigating toward the most promising sector at each step. A manual mode is also available for human-guided zoom sessions with the same iterative frame navigation. Both AI and manual zoom support Mandelbrot and Julia Sets.

Starting with version 1.4.0, tranZoom can render animated GIF and MP4 zoom animations with the tranz zoom auto command — a straight zoom-in path toward any target frame, with configurable frame count, FPS, and duration.

What this tool is not

Not a real-time / interactive fractal explorer (rendering is intentionally CPU-intensive for correctness at depth)
Not limited to a fixed precision (unlike most other fractal tools, which cap at float64)
Not a cloud-based tool — AI zoom uses local LLM models via LMStudio; no external API calls

Key concepts and terminology

Frame: A rectangular region of the complex plane, defined by a center + width. Stored as gmpy2.mpq (exact rationals) to avoid any accumulation of rounding error in coordinates.
Precision: The number of bits of mpfr floating-point precision used for escape-time iteration. Computed automatically from the frame size; never needs to be set manually.
Magnification: Ratio of the default full-set frame area to the current frame area. 1× = full set; 1G× = zoomed in one billion times.
Escape-time iteration: The core Mandelbrot test; larger max_iter produces more detail at high zoom.
Interior tests: Fast algebraic checks (main cardioid, period-2 bulb) that skip the iterative test for points known to be inside the set, speeding up rendering significantly.
Color palette: Six built-in palettes color the exterior (escaped) pixels. The active palette is chosen with --palette (global flag). Positions in the palette are determined by histogram equalization of escape-iteration counts, cycling through the stops 3 times across the range, so the full color range is used regardless of zoom depth or iteration scale. Available palettes: blue-to-yellow-to-brown (classic 16-stop gradient, default), lava (16-stop volcanic gradient), electric-ocean (32-stop abyss-to-magenta-to-lavender gradient), sunset (32-stop indigo-to-amber-to-wine gradient), rgrayscale (8-stop white-to-black gradient, designed for interior coloring), grayscale (8-stop black-to-white gradient).
Interior (Set) coloring: By default, interior points (those that never escape, i.e., inside the Mandelbrot/Julia Set) are rendered as pure black. Passing --set ALGORITHM enables smooth coloring of those points using a separate --set-palette (default rgrayscale); supported algorithms: min (minimum |z| at max depth), max (maximum |z|), angle (angle of z), imaginary (imaginary-weighted average of z). Histogram equalization is applied over the stored values, cycling through the set palette only once (no banding). The rgrayscale set palette goes white (deep interior, low |z|) → black (near boundary, high |z|), so the Set boundary is always dark for contrast with the exterior colors. Both flags are global and apply to all image and zoom commands.
Zoom animation: The tranz zoom auto command renders a straight zoom-in path from a starting frame down to a target magnification and saves it as an animated GIF or MP4 video. Specify any two of --frames, --fps, and --duration to constrain the third. Use --anim gif (default) or --anim mp4 to select the output format.
AI zoom session: The tranz zoom ai command starts an iterative loop: render the current frame, draw a 3×3 thirds grid overlay with green sector labels, send the image to a local LLM vision model, parse the 9-sector scoring response, and move the frame center toward the highest-scoring sector. Supports both Mandelbrot (default) and Julia Set fractals via -f/--fractal. The optional --query flag enables targeted search, blending fractal-quality scores with target-match scores. The loop runs until Ctrl+C or --max-steps is reached.
Manual zoom session: The tranz zoom manual command runs the same iterative frame navigation but prompts the user for a direction at each step (1–9, numpad layout: 5=center, 8=N, 6=E, etc.) instead of querying an LLM. Supports both Mandelbrot and Julia Set fractals.
Sector scoring: Each sector is scored on a 0–100 scale for fractal_score (visual complexity / zoom promise). When targeted search is active, an additional target_match_score (also 0–100) is blended in with a configurable weight.
Image metadata: All tranZoom PNG images embed rich metadata (tranzoom:* PNG text chunks) including frame coordinates, magnification, palette, precision, and (for AI/manual sessions) the full LLM evaluation, model parameters, prompts, and zoom step count.

Frame Representation

A Frame is an exact representation of a rectangular region of the complex plane, it is your view into a fractal, the viewport, the part of the plane to be computed and transformed into an image or visualization. It can be printed by the CLI like:

[(-3/4, 0) ± 5/2] A square Frame, centered on $-3/4+0j$ and with width and height of $5/2$, [(center_re, center_im) ± square_side]; or
[(-3/4, 0) ± (5/2, 5/3)] A rectangular Frame, centered on $-3/4+0j$ and with width of $5/2$ (on the real scale) and height of $5/3$ (on the imaginary scale), [(center_re, center_im) ± (width_re, height_im)].

Frames are stored as gmpy2.mpq (exact rationals) to avoid any accumulation of rounding error in coordinates. You can provide a mpq to the CLI as:

int or float: for example "23" or "23.98205483423723". If the float is given as a string like shown here it will be passed as-is to mpq and will be converted to arbitrary precision rational, i.e., whatever size fraction is needed to represent all decimal places you gave.
rational (recommended): for example " -3/4" or "7916615127197/29003906250000" (note the very important space before the -3/4 that allows the string to not be confused with a parameter by the CLI parser).

Here is an example with mixed use:

" -0.74303" "0.126433" "1611/100000" "0.0176"
will create the Frame:
[(-74303/100000, 126433/1000000) ± (1611/100000, 11/625)]

Here is one example with numbers that would usually NOT be representable with regular float:

" -929554858796448380940239382643467500000001/1250000000000000000000000000000000000000000" "0.13182590420531197049313205638514950000008" "0.00000000000001"
will create the Frame:
[(-929554858796448380940239382643467500000001/1250000000000000000000000000000000000000000,
1647823802566399631164150704814368750001/12500000000000000000000000000000000000000) ± 1/100000000000000]

Frame will keep these numbers exact always, no matter the precision.

For Julia and other uses the Frame can also receive an extra complex number, a point, determined by real and image parts. It will be represented as:

[(center_re, center_im) ± (width_re, height_im) @ (point_re, point_im)]

where the (point_re, point_im) part is added after an @. For example:

[(-3/4, 0) ± (5/2, 5/3) @ (13667/50000, 371/50000)]

Precision

Precision is the number of MPFR (arbitrary-precision floating-point) bits used during fractal iteration. Mandelbrot computation involves repeated complex-plane arithmetic starting from the frame's coordinates; insufficient floating-point precision causes visible artifacts — pixels classified as escaped or non-escaped incorrectly — especially at high magnification where neighboring pixels differ only in the final bits of their coordinates.

TransZoom computes the required precision automatically for every (frame, image size, max-iteration) combination via Frame.Precision() and Image.precision. You never need to set it manually. The estimate is conservative by design: it aims to keep numerical noise far below one output pixel.

The formula is:

precision = max(P_min, ceil(log2(M / h)) + 2 * ceil(log2(N + 1)) + G)

where:

h = min(frame_width / pixel_width, frame_height / pixel_height) — the smaller complex-plane distance that maps to one output pixel (the tighter precision constraint)
M = max(|top_re|, |bottom_re|, |top_im|, |bottom_im|, 1) — the largest coordinate magnitude in the frame; because MPFR precision is relative (not absolute), frames far from the origin need more bits to represent fine detail at a given scale
N — max_iter, the iteration ceiling for the render; the 2 * ceil(log2(N + 1)) term is an iteration guard that grows logarithmically to account for accumulated rounding error over many iterations
G = 88 — _MPFR_MIN_GUARD_BITS, a fixed safety margin of 88 extra bits beyond the bare minimum to distinguish neighboring pixels
P_min = 140 — _MPFR_MIN_PRECISION, the floor (≈42 decimal digits), active for low-magnification frames where the base term is small

The maximum allowed precision is _MPFR_MAX_PRECISION = 300 000 bits (≈90 000 decimal digits). Requesting a frame smaller than that limit raises an error. In practice, deep zooms at moderate image sizes stay well below a few thousand bits.

The computed precision is exposed as:

Frame.Precision(pixel_width, pixel_height, max_iter=...) → int bits
Frame.Context(pixel_width, pixel_height, max_iter=...) → ready-to-use gmpy2.context
Image.precision → int bits (uses the image's own dimensions and current depth)
Image.context → ready-to-use gmpy2.context (same)

Inputs and outputs

Inputs

stdin: not used (except the tranz zoom manual direction prompt, which reads from stdin)
CLI arguments: center coordinates (real + imaginary parts as strings, for exact mpq conversion), frame width/height, output image dimensions
Config file: stored in the OS-native location via transcrypto.utils.config

Outputs

stdout: progress info and saved filename
stderr: warnings/errors/logs (controlled by --verbose)
Output images are saved as <prefix>[-<YYYYMMDDhhmmss>][-<SHA256-20>].png; the prefix defaults to mandel for Mandelbrot and julia for Julia and is set via --prefix; date inclusion is controlled by --date/--no-date; hash (first 20 chars of SHA256, 80 bits) inclusion is controlled by --hash/--no-hash; output directory is set via -o/--out (defaults to the current working directory)

CLI Interface

Quick start

Full / Default

Render the full Mandelbrot set (default, 1024×1024):

$ poetry run tranz --no-date image mandel

1024x1024 Mandelbrot in frame [(-3/4, 0) ± 5/2], precision ± 140 bits, 1 magnification, AUTO iterations...
Pre: 100%|█████████████████████████████████████████████| 256/256 [00:00<00:00, 413.97px/s]
Picked depth 1000, histogram [(1, 24), (2, 26), (3, 58), ('...', 86), (57, 2), (222, 2), (100000, 58)], 12/256 set points
Img: 100%|█████████████████████████████████████████████| 1048576/1048576 [00:14<00:00, 72593.90px/s]
Mandelbrot image 'b934ff27c4e6dede0ecdea8c746ab8f626553ba40e1a402506935e2fd0354f1b' in 19.931 s
Saved to "mandel-b934ff27c4e6dede0ecd.png"

As can be seen, the Frame is stored as rational numbers with arbitrary precision, [(-3/4, 0) ± 5/2], so it is guaranteed to be exact (centered in $-0.75+0j$ and with width of $2.5$). It will pick a precision, in bits, which is the internal float representation (mantissa), and will pick the (max) number of iterations for the generation. The magnification here is 1 because it is the full Mandelbrot set. There will be a progress bar, counting the horizontal lines being produced. The generated image data will be hashed and then saved to a PNG on disk.

Render a well-known zoom ("Seahorse", ~155× magnification) at the default 1024×1024:

Seahorse

poetry run tranz image mandel " -0.74303" "0.126433" "0.01611"

You can also extract details from the set points (the traditionally black part of the image) using --set and --set-palette. For example:

Full / Default

poetry run tranz --set imaginary --set-palette "lava" --palette "rgrayscale" image mandel

See many more examples in Comprehensive example images and zooms.

Palettes

With the --palette global flag you can pick your color scheme for exterior (escaped) pixels. With --set-palette you can pick the color scheme for interior Set points (only visible when --set is also given). We provide the following palettes:

Flag Value	Notes
`"blue-to-yellow-to-brown"` (DEFAULT)	Classic 16-stop gradient
`"lava"`	16-stop volcanic gradient
`"electric-ocean"`	32-stop abyss-to-magenta-to-lavender gradient
`"sunset"`	32-stop indigo-to-amber-to-wine gradient
`"rgrayscale"` (DEFAULT for `--set-palette`)	8-stop white-to-black gradient; white=deep interior, black=near boundary; designed for interior Set-point coloring; cycles once
`"grayscale"`	8-stop black-to-white gradient; black=deep interior, white=near boundary; reverse of `rgrayscale`; cycles once

Command structure

tranz [global flags] <subgroup> <command> [args]

Available subgroup / command combinations:

tranz image mandel — render a Mandelbrot image
tranz image julia — render a Julia Set image
tranz image read — read and inspect a tranZoom image
tranz zoom ai — AI-guided iterative zoom session
tranz zoom manual — human-guided iterative zoom session
tranz zoom auto — automated GIF/MP4 zoom animation
tranz markdown — generate CLI documentation

`tranz` global flags

Flag	Description	Default
`--help`	Show help	off
`--version`	Show version and exit	off
`-v`, `-vv`, `-vvv`, `--verbose`	Verbosity (nothing=ERROR, `-v`=WARNING, `-vv`=INFO, `-vvv`=DEBUG)	ERROR
`--color`/`--no-color`	Force enable/disable colored output (respects `NO_COLOR` env var if not provided)	`--color`
`--threads`	Number of worker processes for rendering (1–N, default: all available cores)	all cores
`-o`/`--out`	Output directory path	current directory
`--prefix`	Filename prefix	None = `mandel`/`julia`
`--date`/`--no-date`	Include date-time (`YYYYMMDDhhmmss`) in filename	`--date`
`--hash`/`--no-hash`	Include 20-char SHA256 hash in filename	`--hash`
`--iterm`/`--no-iterm`	Print image inline in iTerm2 (macOS + iTerm2 only)	off
`--palette`	Color palette for exterior (escaped) pixels; one of `blue-to-yellow-to-brown`, `lava`, `electric-ocean`, `sunset`, `rgrayscale`, `grayscale`	`blue-to-yellow-to-brown`
`--set-palette`	Color palette for interior Set points (used only when `--set` is given)	`rgrayscale`
`--set`	Algorithm for interior Set point coloring; one of `min`, `max`, `angle`, `imaginary`; omit to keep interior black	None
`-m`/`--model`	LMStudio vision model identifier to load	`qwen3-vl-32b-instruct@q8_0`
`--spec-tokens`	Speculative decoding tokens	model default
`--seed`	Random seed for the model	random
`-c`/`--context`	Context window size in tokens	model default
`-x`/`--temperature`	Sampling temperature	`0.15`
`--gpu`	GPU usage ratio (`0.0`–`1.0`)	`0.80`
`--gpu-layers`	Number of model layers to offload to GPU	`-1` (as many as possible)
`--fp16`	Use FP16 precision	off
`--mmap`/`--no-mmap`	Use memory-mapped model files	on
`--flash`/`--no-flash`	Use flash attention	on
`--kv-cache`	Key-value cache size	model default
`--timeout`	Model operation timeout in seconds	`300.0`

`tranz image` subgroup flags

These flags apply to all tranz image commands and must be placed between image and the sub-command name:

tranz [global flags] image [-w W] [-h H] [-s S] [--iter N] [--mark COORD] <mandel|julia|read> [args]

Flag	Description	Default
`-w`/`--width`	Output image width in pixels (16–16384)	1024
`-h`/`--height`	Output image height in pixels (16–16384)	1024
`-s`/`--size`	Max pixel side; overrides `-w`/`-h` and scales the other dimension proportionally to match the frame aspect ratio	None (use `-w`/`-h`)
`-i`/`--iter`	Override max iterations (depth); `1000`–4294967295	automatic adaptive search
`--mark`	Draw a crosshair at this complex coordinate, formatted as `"(re, im)"`	None
`--mark-color`	Color of the crosshair; one of `black`, `white`, `red`, `green`, `blue`, `yellow`, `cyan`, `magenta`	`red`
`--mark-width`	Line width of the crosshair (1–50)	`1`

`tranz zoom` subgroup flags

These flags apply to all tranz zoom commands and must be placed between zoom and the sub-command name:

tranz [global flags] zoom [-w W] [-h H] [-s S] [-f FRACTAL] [-n STEPS] [--julia-re RE] [--julia-im IM] <ai|manual|auto> [args]

Flag	Description	Default
`-w`/`--width`	Output image width in pixels (16–16384)	512
`-h`/`--height`	Output image height in pixels (16–16384)	512
`-s`/`--size`	Max pixel side; overrides `-w`/`-h` and scales proportionally	None (use `-w`/`-h`)
`-f`/`--fractal`	Fractal type: `mandelbrot` or `julia`	`mandelbrot`
`--julia-re`	Real part of the Julia Set constant `c`	`'0.27334'`
`--julia-im`	Imaginary part of the Julia Set constant `c`	`'0.00742'`
`-n`/`--max-steps`	Max zoom steps; `0` = unlimited (Ctrl+C to stop)	`0`

Palette flags (--palette, --set-palette, --set) are global flags (placed before the subgroup name) and apply to all zoom commands as well as image commands.

CLI Commands Documentation

Auto-generated CLI reference:

tranz documentation

`tranz image mandel` — Render a Mandelbrot image

poetry run tranz [global flags] image [-w WIDTH] [-h HEIGHT] [--iter N] mandel [CENTER_RE] [CENTER_IM] [F_WIDTH] [F_HEIGHT]

Positional arguments (all optional; defaults show the full Mandelbrot set):

Argument	Description	Default
`CENTER_RE`	Real part of the center point (string, for exact precision); or a path to an existing tranZoom PNG — the frame is then read from that image's metadata, and the remaining frame arguments are ignored	`'-0.75'`
`CENTER_IM`	Imaginary part of the center point (string, for exact precision)	`'0'`
`F_WIDTH`	Width of the frame in the real plane	`'2.5'`
`F_HEIGHT`	Height of the frame in the imaginary plane	same as `F_WIDTH`

Image size and render options are set at the tranz image subgroup level (see above).

Tip — re-render from a saved image: pass a tranZoom PNG path as CENTER_RE to pick up exactly the same frame:

poetry run tranz image mandel "/path/to/saved.png"

The command:

Constructs a Frame from the given coordinates using gmpy2.mpq exact arithmetic
Calculates the required mpfr precision automatically based on zoom depth
When --iter is not given, runs an adaptive pre-pass on a tiny 16×16 render to estimate the optimal max_iter for the frame (with a 1.5× safety margin); otherwise uses the value supplied
Renders all pixels in parallel using ProcessPoolExecutor (one process per available CPU core, up to 16), each writing an interleaved subset of rows; results are merged into the final image
Each process uses the escape-time algorithm with cardioid/period-2 bulb interior shortcuts and histogram-equalized color palette
Saves the PNG to <prefix>[-<YYYYMMDDhhmmss>][-<SHA256-20>].png in the working directory (or the path given by -o/--out)

See below for many example outputs.

`tranz image julia` — Render a Julia Set image

poetry run tranz [global flags] image [-w WIDTH] [-h HEIGHT] [-s SIZE] [--iter N] [--mark COORD] julia [POINT_RE] [POINT_IM] [CENTER_RE] [CENTER_IM] [F_WIDTH] [F_HEIGHT]

Positional arguments (all optional; defaults show the "Julia Suzana" set):

Argument	Description	Default
`POINT_RE`	Real part of the Julia constant `c`; or a path to an existing tranZoom PNG — the Julia constant is then read from that image's `tranzoom:frame:julia_re` metadata	`'0.27334'`
`POINT_IM`	Imaginary part of the Julia constant `c`	`'0.00742'`
`CENTER_RE`	Real part of the frame center	`'0'`
`CENTER_IM`	Imaginary part of the frame center	`'0'`
`F_WIDTH`	Width of the frame in the real plane	`'1.8'`
`F_HEIGHT`	Height of the frame in the imaginary plane	`'2.2'`

Image size and render options are set at the tranz image subgroup level (see above).

Tip — proportional sizing: use -s instead of -w/-h so the output image always matches the frame's aspect ratio:

poetry run tranz --palette electric-ocean image -s 1024 julia

Tip — re-render from a saved image: pass a tranZoom PNG path as POINT_RE to pick up the same Julia constant:

poetry run tranz image julia "/path/to/saved.png"

`tranz image read` — Read a tranZoom image

poetry run tranz [--iterm] image read <IMAGE_PATH>

Reads an existing tranZoom PNG and pretty-prints all embedded metadata:

$ poetry run tranz image read mandel-38824cdaa58b64496ebf.png

'/path/to/mandel-38824cdaa58b64496ebf.png'
1024x1024 (wxh) / 38824cdaa58b64496ebfd86facf4d4ba4596ab18db95ac97afd643a7a892ff83

{
  "tranzoom:frame:fractal": "mandelbrot",
  "tranzoom:frame:top_re": "-7436499/10000000",
  ...
}

Use --iterm (global flag) to also display the image inline (macOS + iTerm2 only).

`tranz zoom ai` — AI-guided fractal zoom search

poetry run tranz [global flags] zoom [-w WIDTH] [-h HEIGHT] [-n STEPS] ai \
  [CENTER_RE] [CENTER_IM] [F_WIDTH] [F_HEIGHT] [-q QUERY] [--reason] [--memory N]

Starts an AI-guided iterative zoom session:

Renders the current frame (default: 512×512, configurable via tranz zoom -w/-h)
Draws a 3×3 thirds grid with green sector numbers on top
Sends the image to the LLM vision model with a fractal-scoring prompt
Parses the structured response (9 sector scores)
Navigates the frame toward the highest-scoring sector (by ~1/3 of the frame size)
Saves the image with full LLM evaluation embedded in PNG metadata
Repeats until Ctrl+C or --max-steps is reached

Supports both Mandelbrot (default) and Julia Set fractals: use -f julia (and optionally --julia-re/--julia-im) on the tranz zoom subgroup callback.

Positional frame arguments:

Argument	Description	Default
`CENTER_RE`	Real part of the starting frame center; or a path to an existing tranZoom PNG (frame is read from image metadata; other frame arguments ignored)	`'-0.75'` (full set)
`CENTER_IM`	Imaginary part of the starting frame center	`'0'`
`F_WIDTH`	Starting frame width	`'2.5'`
`F_HEIGHT`	Starting frame height	same as `F_WIDTH`

Command-level options (on tranz zoom ai only):

Option	Description	Default
`-q`/`--query`	Targeted search query added to the scoring prompt	None
`--reason/--no-reason`	Include LLM reasoning text per sector	off
`--memory`	Number of previous steps in LLM chat history	`5`

Image size and step count are set at the tranz zoom subgroup level (see above); --iterm is a global flag.

Example — start from the full set, zoom using default model at default 512×512:

poetry run tranz zoom ai

Example — start from the Seahorse Tail, targeted search, 10 steps, show images, custom model:

poetry run tranz --iterm -m "qwen3-vl-32b-instruct@q8_0" -x 0.7 zoom -n 10 ai \
  " -0.7436499" "0.13188204" "0.00073801" \
  -q "spiral"

Example — resume a previous session from a saved tranZoom PNG (frame read from image metadata):

poetry run tranz zoom ai "/path/to/saved.png"

`tranz zoom manual` — Manually-guided fractal zoom

poetry run tranz [--iterm] zoom [-w WIDTH] [-h HEIGHT] [-n STEPS] manual \
  [CENTER_RE] [CENTER_IM] [F_WIDTH] [F_HEIGHT]

Same iterative rendering loop as tranz zoom ai, but at each step the user types a direction (1–9, numpad layout: 5=center/zoom-in, 8=N, 2=S, 4=W, 6=E, 7=NW, 9=NE, 1=SW, 3=SE) instead of querying an LLM. The evaluation is stored in PNG metadata labeled as HUMAN.

Positional frame arguments work the same way as tranz zoom ai: pass a tranZoom PNG path as CENTER_RE to start the session from the frame stored in that image's metadata.

Supports both Mandelbrot (default) and Julia Set fractals via -f/--fractal on the tranz zoom subgroup callback.

Note: tranz zoom manual does not require the AI model flags; it does not load an LLM.

`tranz zoom auto` — Automated GIF/MP4 zoom animation

poetry run tranz [global flags] zoom [-w WIDTH] [-h HEIGHT] [-s SIZE] [-f FRACTAL] auto \
  [CENTER_RE] [CENTER_IM] [F_WIDTH] [F_HEIGHT] [DEST_MAGNIFICATION_10] \
  [--anim TYPE] [--duration D] [--frames N] [--fps FPS] [--loop L] [--save-frames]

Renders a straight zoom-in animation from a starting frame to a target magnification and saves it as an animated GIF or MP4 file. Specify any two of --duration, --frames, and --fps to constrain the third; the command validates that all three resulting values are within allowed bounds.

The zoom progression is geometrically uniform: each successive frame is scaled by a fixed rational factor computed so that the product of all per-frame zoom steps equals exactly the requested total magnification. Animation metadata such as initial frame size, zoom step, FPS, duration, frame count, and loop count is stored with the final animated output; if you save intermediate PNG frames, they are written as regular tranZoom still images and do not currently include per-frame tranzoom:animation:* PNG text chunks.

Positional arguments:

| Argument | Description | Default | | --- | --- | | CENTER_RE | Real part of the starting frame center; or a path to an existing tranZoom PNG (frame read from image metadata) | '-0.75' (full set) | | CENTER_IM | Imaginary part of the starting frame center | '0' | | F_WIDTH | Starting frame width | '2.5' | | F_HEIGHT | Starting frame height | same as F_WIDTH | | DEST_MAGNIFICATION_10 | Zoom exponent: total zoom is 10^N; e.g., 2.0 = 100× zoom | 1.0 |

Command-level options:

Option	Description	Default
`--anim`	Output format: `gif` or `mp4`	`gif`
`--duration`	Total animation duration in seconds (0.1–45000)	None (computed)
`--frames`	Number of frames (3–100000)	None (computed)
`--fps`	Frames per second (0.1–30)	None (computed)
`--loop`	Number of GIF loops; `0` = infinite (ignored for MP4)	`0`
`--save-frames/--no-save-frames`	Save each intermediate PNG frame to disk	off
`--max-iter`	Override max iterations (depth)	automatic adaptive search
`--mark`	Draw a crosshair at this complex coordinate on every frame	None
`--mark-color`	Crosshair color	`red`
`--mark-width`	Crosshair line width (1–50)	`1`

Image size and fractal type are set at the tranz zoom subgroup level (see above); palette flags are global flags.

Example — animate a 10× zoom into the Seahorse Tail, 4 s at 10 FPS, 220×220 pixels:

poetry run tranz --no-date zoom -s 220 auto \
  " -5578776469/7500000000" "8244620127/62500000000" "0.00073801" "0.00073801" "1" \
  --fps 10 --duration 4

To produce an MP4 instead of a GIF, add --anim mp4.

Comprehensive example images and zooms

You can run all these at once by executing scripts/make_examples.sh.

Full / Default (×1)

Full / Default

Render the full Mandelbrot set with all the default values (image size 1024×1024, centered in $-0.75+0j$ and with width of $2.5$, a good frame that contains the whole set):

$ poetry run tranz --no-date image mandel

1024x1024 Mandelbrot in frame [(-3/4, 0) ± 5/2], precision ± 140 bits, 1 magnification, AUTO iterations...
Pre: 100%|█████████████████████████████████████████████| 256/256 [00:00<00:00, 414.11px/s]
Picked depth 1000, histogram [(1, 24), (2, 26), (3, 58), ('...', 86), (57, 2), (222, 2), (100000, 58)], 12/256 set points
Img: 100%|█████████████████████████████████████████████| 1048576/1048576 [00:14<00:00, 74181.35px/s]
Mandelbrot image 'b934ff27c4e6dede0ecdea8c746ab8f626553ba40e1a402506935e2fd0354f1b' in 16.469 s
Saved to "mandel-b934ff27c4e6dede0ecd.png"

This is what tranZoom considers "1 magnification", and will measure other magnifications against this size.

Set Interior Coloring

Full / Default

You can also extract details from the set points (the traditionally black part of the image) using --set and --set-palette. For example:

$ poetry run tranz --set imaginary --set-palette "lava" --palette "rgrayscale" --no-date image mandel

1024x1024 Mandelbrot in frame [(-3/4, 0) ± 5/2], precision ± 140 bits, 1 magnification, AUTO iterations, "imaginary" interior...
Pre: 100%|█████████████████████████████████████████████| 256/256 [00:00<00:00, 308.62px/s]
Picked depth 1000, histogram [(1, 24), (2, 26), (3, 58), ('...', 86), (57, 2), (222, 2), (100000, 58)], 12/256 set points
Img: 100%|█████████████████████████████████████████████| 1048576/1048576 [00:19<00:00, 53433.31px/s]
Mandelbrot image 'c530e1e75c1660b4d274349fc659ab4d8d9c4a7e5eb0642d50f44b5db188c13e' in 22.413 s
Saved to "mandel-c530e1e75c1660b4d274.png"

Seahorse (×155)

Seahorse

Render a well-known zoom ("Seahorse") to a 1024×1024 image (default size):

$ poetry run tranz --no-date image mandel " -0.74303" "0.126433" "0.01611"

1024x1024 Mandelbrot in frame [(-74303/100000, 126433/1000000) ± 1611/100000], precision ± 140 bits, 155.183 magnification, AUTO iterations...
Pre: 100%|█████████████████████████████████████████████| 256/256 [00:00<00:00, 512.82px/s]
Picked depth 9276, histogram [(24, 7), (25, 14), (26, 14), ('...', 153), (3215, 1), (6184, 1), (100000, 66)], 9/256 set points
Img: 100%|█████████████████████████████████████████████| 1048576/1048576 [02:24<00:00, 7245.57px/s]
Mandelbrot image 'e70bc149bc2fd3aff8ce4d8aed79c878f373bb5f5ee82fb866584e0cf9858793' in 2.478 min
Saved to "mandel-e70bc149bc2fd3aff8ce.png"

This one definitively demands more time than even much deeper zooms. It has the features that make an image demand computation: a lot of set points (half the image is black, i.e., set points) and a larger iteration depth.

Seahorse Tail (×3k)

Seahorse Tail

Render a "Seahorse Tail" at default 1024×1024:

$ poetry run tranz --set imaginary --no-date image mandel " -0.7436499" "0.13188204" "0.00073801"

1024x1024 Mandelbrot in frame [(-7436499/10000000, 3297051/25000000) ± 73801/100000000], precision ± 140 bits, 3.387 k magnification, AUTO iterations,
"imaginary" interior...
Pre: 100%|█████████████████████████████████████████████| 256/256 [00:00<00:00, 64996.48px/s]
Picked depth 1000, histogram [(36, 5), (37, 9), (38, 15), ('...', 224), (415, 1), (464, 1), (649, 1)], 0/256 set points
Img: 100%|█████████████████████████████████████████████| 1048576/1048576 [00:08<00:00, 129166.61px/s]
Mandelbrot image 'bc8befe1492f4d296cf93994ba201ef06c3fa4858a47a657bb7f136f42bceb5d' in 9.700 s
Saved to "mandel-bc8befe1492f4d296cf9.png"

This image is relatively fast to generate (despite the zoom level, it has very little interior regions), so we use it in the unit and integration tests to make sure we are operating consistently. If the hash of this image changes, remember to change it in src/tranzoom/cli/base.py.

Seahorse Tail Zoom

GIF	MP4

You can easily make animations!

$ poetry run tranz --no-date zoom -s 220 auto " -5578776469/7500000000" "8244620127/62500000000" "0.00073801" "0.00073801" "1" --fps 10 --duration 4

Producing 220x220 10^1.00 zoom animation, 4.000 s long, at 10.00 FPS, with 40 frames, 106.08% per step (48455/45677), final magnification error 0.0000%...

Frame 1 / 40

220x220 Mandelbrot in frame [(-5578776469/7500000000, 8244620127/62500000000) ± 73801/100000000], precision ± 140 bits, 3.387 k magnification, AUTO
iterations...

[...]

Success: GIF '91b99d972c26a6a4d6116064b4528136a9104436cac3d9f48d679df37a875d97' in 39.587 s
Saved GIF to "mandel-91b99d972c26a6a4d611.gif"

To make that an MP4, just add --anim mp4 to the command.

Julia Suzana (×1)

Julia Suzana

Render a "Julia Suzana" at -s/--size 1024, one of the possible Julia Set:

$ poetry run tranz --no-date --palette electric-ocean image -s 1024 julia

838x1024 Julia in frame [(0, 0) ± (9/5, 11/5) @ (13667/50000, 371/50000)], precision ± 140 bits, 1 magnification, AUTO iterations...
Pre: 100%|█████████████████████████████████████████████| 256/256 [00:01<00:00, 151.95px/s]
Picked depth 1000, histogram [(2, 20), (3, 32), (4, 18), ('...', 58), (44, 2), (45, 2), (100000, 124)], 31/256 set points
Img: 100%|█████████████████████████████████████████████| 858112/858112 [00:27<00:00, 31524.71px/s]
Julia image '28f147dcfc6190d94bbbfece396c56ae074bb3cae14be5040446dc5fb40984f8' in 30.267 s
Saved to "julia-28f147dcfc6190d94bbb.png"

Julia Suzana Wave (×427)

Julia Suzana

Render a "Julia Suzana Wave" at -s/--size 1024:

$ poetry run tranz --palette electric-ocean --set max --set-palette sunset --no-date image -s 512 julia "13667/50000" "371/50000" " -313420497/429687500" "0.6567" "0.00544" "0.004"

512x377 Julia in frame [(-313420497/429687500, 6567/10000) ± (17/3125, 1/250) @ (13667/50000, 371/50000)], precision ± 140 bits, 426.597 magnification,
AUTO iterations, "max" interior...
Pre: 100%|█████████████████████████████████████████████| 256/256 [00:01<00:00, 137.09px/s]
Picked depth 1819, histogram [(43, 8), (44, 14), (45, 14), ('...', 93), (208, 1), (1213, 1), (100000, 125)], 30/256 set points
Img: 100%|█████████████████████████████████████████████| 193024/193024 [00:10<00:00, 17614.26px/s]
Julia image 'd7b19b0f1783bb38127d2948140e2379c19656ff4923b7244f25da7fbf322a2a' in 13.907 s
Saved to "julia-d7b19b0f1783bb38127d.png"

If the hash of this image changes, remember to change it in src/tranzoom/cli/base.py.

Powers of 1000

Centering on exactly:

$-0.7436438870371587047521915061147740000000008 + 0.13182590420531197049313205638514950000008j$

or, if you want to use as parameters:

"(-0.7436438870371587047521915061147740000000008, 0.13182590420531197049313205638514950000008)"

We have, for fun, generated a sequence of powers of 1000, demonstrating the amazing power of the infinite. The view size of each image is always $2.5$ times some power of 1000.

Bits	Size $2.5\times$	Equivalent real-world size / Landmark examples
$140$	$1$	$\sim 10^{11}$ light-years = Observable-universe scale, about $93$ billion light-years across.
$140$	$10^{-3}$	$\sim 10^{8}$ light-years = Cosmic-web / supercluster scale: galaxy walls, voids.
$140$	$10^{-6}$	$\sim 10^{5}$ light-years = Galaxy scale: the Milky Way is about $100{,}000$ light-years across.
$146$	$10^{-9}$	$\sim 100$ light-years = Local stellar-neighborhood scale: nearby star groups, nebulae, and star-forming regions.
$156$	$10^{-12}$	$\sim 0.1$ light-year = Outer-solar-system scale: comparable to the distant Oort-cloud region.
$166$	$10^{-15}$	$\sim 10^{9},\mathrm{km}$ = Inner-to-middle solar-system scale: comparable to giant-planet orbital distances.
$176$	$10^{-18}$	$\sim 10^{6},\mathrm{km}$ = Star / giant-planet scale: the Sun’s diameter is about $1.39 \times 10^{6},\mathrm{km}$.
$186$	$10^{-21}$	$\sim 10^{3},\mathrm{km}$ = Planetary-geography scale: large countries, small moons, continent-scale weather systems.
$196$	$10^{-24}$	$\sim 1,\mathrm{km}$ = Human landscape scale: mountains, city districts, bridges, runways.
$206$	$10^{-27}$	$\sim 1,\mathrm{m}$ = Human/body scale: a person, table, doorway, musical instrument.
$216$	$10^{-30}$	$\sim 1,\mathrm{mm}$ = Small visible-object scale: sand grains, seeds, insect parts, raindrops.
$226$	$10^{-33}$	$\sim 1,\mu\mathrm{m}$ = Cell/microbe scale: bacteria, organelles, and wavelengths near visible/infrared light.
$236$	$10^{-36}$	$\sim 1,\mathrm{nm}$ = Molecule scale: DNA width, proteins, small molecular machines.
$246$	$10^{-39}$	$\sim 1,\mathrm{pm}$ = Deep atomic/electron-cloud scale: smaller than typical atomic diameters, which are around $10^{-10},\mathrm{m}$.
$256$	$10^{-42}$	$\sim 1,\mathrm{fm}$ = Atomic nucleus / proton scale: the proton rms charge radius is about $8.4075 \times 10^{-16},\mathrm{m}$.
$266$	$10^{-45}$	$\sim 1,\mathrm{am}$ = Quarks and leptons: elementary particles in the Standard Model

Configuration

Config files are stored in OS-native locations via transcrypto.utils.config:

macOS: ~/Library/Application Support/tranzoom/config.bin
Linux: ~/.config/tranzoom/config.bin
Windows: %APPDATA%\tranzoom\config.bin

Color and formatting

The CLI respects the NO_COLOR environment variable and the --no-color / --color flag. Rich markup is used for console output — see Rich markup conventions.

Exit codes

Code	Meaning
0	Success
1	Generic failure
2	CLI usage error (bad arguments)

Project Design

Modules / packages

Component	Responsibility
`tranz.py`	`tranz` CLI entry point — global options, `tranz markdown`
`cli/base.py`	Shared CLI options, defaults, `DEFAULT_MANDELBROT_FRAME`
`cli/imagecommand.py`	`tranz image mandel`, `tranz image julia`, and `tranz image read` command implementations
`cli/zoomcommand.py`	`tranz zoom ai`, `tranz zoom manual`, and `tranz zoom auto` command implementations
`core/fractal.py`	`Mandelbrot()` and `Julia()` renderers — fractal math
`core/frame.py`	`Frame` class, `Fractal` enum, and base coordinate math
`core/image.py`	`Image` class; image utilities, overlays, iTerm2 printing, metadata helpers
`core/palette.py`	Palette definitions and color mapping
`core/queries.py`	AI prompt templates and Pydantic models for structured LLM responses
`core/ai.py`	`ZoomLoop()` and `ManualLoop()` — iterative AI and manual zoom session logic
`utils/template.py`	Template for new utility modules

Performance characteristics

Rendering is CPU-bound. Time scales roughly with width × height × max_iter × precision_overhead. For deep zooms, higher precision means slower mpfr arithmetic (roughly linear in the number of bits). For very deep zooms (>100 bits precision), rendering a 256×256 image at 50k iterations can take minutes to hours. The tqdm progress bar shows per-row speed.

The Mandelbrot() function pre-computes all X-axis mpfr values once per image and reuses them across rows, which is an important optimization since mpfr construction is expensive at high precision.

Development Instructions

File structure

.
├── CHANGELOG.md                  ⟸ latest changes/releases
├── LICENSE
├── Makefile
├── tranz.md                      ⟸ auto-generated CLI doc (by `make docs` or `make ci`)
├── poetry.lock                   ⟸ maintained by Poetry; do not manually edit
├── pyproject.toml                ⟸ most important configurations live here
├── README.md                     ⟸ this documentation
├── SECURITY.md                   ⟸ security policy
├── requirements.txt
├── .editorconfig
├── .gitignore
├── .pre-commit-config.yaml       ⟸ pre-submit configs
├── .github/
│   ├── copilot-instructions.md
│   ├── dependabot.yaml
│   └── workflows/
│       ├── ci.yaml
│       └── codeql.yaml
├── .vscode/
│   ├── extensions.json
│   └── settings.json
├── scripts/
│   ├── make_examples.sh          ⟸ renders example images at all zoom levels to test/data/images
│   └── template.py               ⟸ template for standalone executable scripts
├── src/
│   └── tranzoom/
│       ├── __init__.py           ⟸ version lives here
|       ├── tranz.py              ⟸ TranZoom `tranz` CLI entry point
│       ├── py.typed
│       ├── cli/
│       │   ├── __init__.py
│       │   ├── base.py           ⟸ shared CLI options, frame defaults, config dataclasses
│       │   ├── imagecommand.py   ⟸ `tranz image mandel` and `tranz image read` implementations
│       │   └── zoomcommand.py    ⟸ `tranz zoom ai`, `tranz zoom manual`, and `tranz zoom auto` implementations
│       ├── core/
│       │   ├── __init__.py
│       │   ├── ai.py             ⟸ ZoomLoop() and ManualLoop() — zoom session logic
│       │   ├── fractal.py        ⟸ Mandelbrot() renderer
│       │   ├── frame.py          ⟸ Frame class, Fractal enum; base for computation
│       │   ├── image.py          ⟸ Image class, overlays, iTerm2, metadata helpers
│       │   ├── palette.py        ⟸ Palette definitions
│       │   └── queries.py        ⟸ AI prompt templates and Pydantic response models
│       └── utils/
│           ├── __init__.py
│           └── template.py       ⟸ template for new utility modules
├── tests/
│   ├── tranz_test.py
│   ├── cli/
│   │   ├── base_test.py          ⟸ seahorse tail hash regression test
│   │   └── imagecommand_test.py
│   └── data/
│       └── images/               ⟸ example renders at 7 zoom levels and powers of 1000
└── tests_integration/
    └── test_installed_cli.py

Development Setup

Install Python

On Linux:

sudo apt-get update && sudo apt-get upgrade
sudo apt-get install git python3 python3-dev python3-venv build-essential software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt-get update
sudo apt-get install python3.12  # or python3.13 or python3.14

On macOS:

brew update && brew upgrade && brew cleanup -s
brew install git python@3.12  # or python3.13 or python3.14

Note: gmpy2 requires the GMP, MPFR, and MPC C libraries. On macOS: brew install gmp mpfr mpc. On Linux: sudo apt-get install libgmp-dev libmpfr-dev libmpc-dev.

Install Poetry (recommended: `pipx`)

Poetry reference.

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install poetry
poetry --version

If you will use PyPI to publish:

poetry config pypi-token.pypi <TOKEN>

Make sure `.venv` is local

poetry config virtualenvs.in-project true

Get the repository

git clone https://github.com/balparda/tranzoom.git
cd tranzoom

Create environment and install dependencies

poetry env use python3.12    # creates the .venv with the correct Python version
poetry sync                  # install all dependencies from poetry.lock
poetry env info              # verify environment
poetry run tranz --help      # smoke test
make ci                      # should pass on clean repo

To activate the environment:

source .venv/bin/activate
# ... work ...
deactivate

Optional: VSCode setup

This repo ships a .vscode/settings.json configured to use ./.venv/bin/python, run pytest, format with Ruff, and use Google-style docstrings. Recommended extensions:

Python (ms-python.python)
Python Environments (ms-python.vscode-python-envs)
Python Debugger (ms-python.debugpy)
Pylance (ms-python.vscode-pylance)
Mypy Type Checker (ms-python.mypy-type-checker)
Ruff (charliermarsh.ruff)
autoDocstring (njpwerner.autodocstring)
Code Spell Checker (streetsidesoftware.code-spell-checker)
markdownlint (davidanson.vscode-markdownlint)
Markdown All in One (yzhang.markdown-all-in-one)
GitHub Copilot (github.copilot)

Build

poetry build   # builds wheel + sdist in dist/

Run locally

poetry run tranz --help
poetry run tranz image mandel    # full set, 1024×1024

Testing

Unit tests / Coverage

make test               # plain test run (no integration tests)
make integration        # run the integration tests
poetry run pytest -vvv  # verbose

make cov  # coverage: poetry run pytest --cov=src --cov-report=term-missing

Test tags defined in pyproject.toml:

Tag	Meaning
`slow`	test takes > 1s
`flaky`	known flaky test — avoid
`stochastic`	may fail with very low probability

Filter by tag:

poetry run pytest -vvv -m slow

Find slow tests:

poetry run pytest -vvv -q --durations=20

Find flaky tests:

make flakes  # runs all tests 100 times

Instrumenting your code

source .venv/bin/activate
pyinstrument -r html -o profile.html -- $(which mandel) gen " -0.74303" "0.126433" "0.01611"
deactivate

Integration / e2e tests

Integration tests build a wheel, install it into a fresh temporary virtualenv, and run the console scripts. Run with:

make integration
# or:
poetry run pytest -m integration -q

Linting / formatting / static analysis

make lint  # poetry run ruff check .
make fmt   # poetry run ruff format .

poetry run ruff format --check --diff .  # check formatting without rewriting

Type checking

make type  # poetry run mypy src tests tests_integration

Documentation updates

CLI reference is auto-generated from the CLI source code:

make docs  # regenerates tranz.md
# or:
poetry run tranz markdown > tranz.md

Always run make ci before committing — it runs linting, type checking, tests, and regenerates docs and requirements.txt.

Versioning and releases

Versioning scheme

Patch: bug fixes / docs / small improvements.
Minor: new features or non-breaking changes.
Major: breaking changes (command renames, incompatible output formats).

See: CHANGELOG.md

Updating versions

Bump project version (patch/minor/major)

poetry version minor   # 1.0.0 → 1.1.0
poetry version patch   # 1.0.0 → 1.0.1
poetry version 1.2.3   # explicit version

Also update src/tranzoom/__init__.py to match!

Update dependency versions

poetry update                      # update poetry.lock to latest compatible versions
poetry cache clear PyPI --all      # if cache issues
poetry add "pkg>=1.2.3"            # add prod dependency
poetry add -G dev "pkg>=1.2.3"     # add dev dependency

Exporting the `requirements.txt` file

make req  # poetry export --format requirements.txt --without-hashes --output requirements.txt

CI and docs

make ci  # runs lint, type check, tests, docs, requirements — do this before every commit

Git tag and commit

git commit -a -m "release version 1.0.0"
git tag 1.0.0
git push && git push --tags

Publish to PyPI

poetry config pypi-token.pypi <TOKEN>  # once, if not already configured
poetry build
poetry publish

Security

Please refer to the security policy in SECURITY.md for supported versions and how to report vulnerabilities.

The project uses CodeQL (weekly + on every push) and dependabot (weekly dependency updates) to keep the codebase secure and up-to-date.

Troubleshooting

Enable debug output

poetry run tranz -vvv image mandel ...   # DEBUG level logging

`gmpy2` installation issues

On macOS, gmpy2 requires the GMP, MPFR, and MPC C libraries. Install them first:

brew install gmp mpfr mpc
poetry sync

On Linux:

sudo apt-get install libgmp-dev libmpfr-dev libmpc-dev
poetry sync

Rendering is very slow

Reduce image size: tranz -w 256 -h 256 image mandel ...
max_iter is auto-scaled with zoom depth; very deep zooms are inherently slow
Very high precision (> 1000 bits, i.e., zoom > ~10^300) will always be slow — this is expected

Thanks! Daniel Balparda & Bella Keri

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

1.9.0

Jun 11, 2026

1.8.2

Jun 8, 2026

1.8.1

Jun 6, 2026

1.8.0

Jun 6, 2026

1.7.0

Jun 4, 2026

1.6.3

Jun 3, 2026

1.6.2

Jun 2, 2026

1.6.1

Jun 1, 2026

1.6.0

May 30, 2026

1.5.2

May 27, 2026

1.5.1

May 26, 2026

1.4.1

May 21, 2026

This version

1.4.0

May 21, 2026

1.3.0

May 17, 2026

1.1.0

May 14, 2026

1.0.0

May 10, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tranzoom-1.4.0.tar.gz (101.0 kB view details)

Uploaded May 21, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

tranzoom-1.4.0-py3-none-any.whl (89.2 kB view details)

Uploaded May 21, 2026 Python 3

File details

Details for the file tranzoom-1.4.0.tar.gz.

File metadata

Download URL: tranzoom-1.4.0.tar.gz
Upload date: May 21, 2026
Size: 101.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: poetry/2.1.3 CPython/3.13.5 Darwin/25.4.0

File hashes

Hashes for tranzoom-1.4.0.tar.gz
Algorithm	Hash digest
SHA256	`8011571613559dba34b94f8cf212ce0203c39ea5c4100870acaae1b96ecfc3fa`
MD5	`1e276467a2eca7980a7da60fd830074c`
BLAKE2b-256	`13ec2fbcc0d5c1c504da638b22c7b2e30196b2f7099b8e28d89a9a7a174ca4b2`

See more details on using hashes here.

File details

Details for the file tranzoom-1.4.0-py3-none-any.whl.

File metadata

Download URL: tranzoom-1.4.0-py3-none-any.whl
Upload date: May 21, 2026
Size: 89.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: poetry/2.1.3 CPython/3.13.5 Darwin/25.4.0

File hashes

Hashes for tranzoom-1.4.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`4f6fe3dc36139b63bdf791af46d0a50675b32500de4f6c1b887f31620630c258`
MD5	`b05c76e6f5098535deb8f33cc020f722`
BLAKE2b-256	`4013ddf0743aeb575ca745eb1cb648340dbdbe2ba50cf6bab9fba2dd8aa4d6e1`

See more details on using hashes here.

tranzoom 1.4.0

Navigation

Verified details

Project links

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

tranZoom

Table of contents

License

Third-party notices

Contributions and inbound licensing

Installation

Supported platforms

Known dependencies (Prerequisites)

Context / Problem Space

What this tool is

What this tool is not

Key concepts and terminology

Frame Representation

Precision

Inputs and outputs

Inputs

Outputs

CLI Interface

Quick start

Palettes

Command structure

tranz global flags

tranz image subgroup flags

tranz zoom subgroup flags

CLI Commands Documentation

tranz image mandel — Render a Mandelbrot image

tranz image julia — Render a Julia Set image

tranz image read — Read a tranZoom image

tranz zoom ai — AI-guided fractal zoom search

tranz zoom manual — Manually-guided fractal zoom

tranz zoom auto — Automated GIF/MP4 zoom animation

Comprehensive example images and zooms

Full / Default (×1)

Set Interior Coloring

Seahorse (×155)

Seahorse Tail (×3k)

Seahorse Tail Zoom

Julia Suzana (×1)

Julia Suzana Wave (×427)

Powers of 1000

Configuration

Color and formatting

Exit codes

Project Design

Modules / packages

Performance characteristics

Development Instructions

File structure

Development Setup

Install Python

Install Poetry (recommended: pipx)

Make sure .venv is local

Get the repository

Create environment and install dependencies

Optional: VSCode setup

Build

Run locally

Testing

Unit tests / Coverage

Instrumenting your code

Integration / e2e tests

Linting / formatting / static analysis

Type checking

Documentation updates

Versioning and releases

Versioning scheme

Updating versions

Bump project version (patch/minor/major)

Update dependency versions

Exporting the requirements.txt file

`tranz` global flags

`tranz image` subgroup flags

`tranz zoom` subgroup flags

`tranz image mandel` — Render a Mandelbrot image

`tranz image julia` — Render a Julia Set image

`tranz image read` — Read a tranZoom image

`tranz zoom ai` — AI-guided fractal zoom search

`tranz zoom manual` — Manually-guided fractal zoom

`tranz zoom auto` — Automated GIF/MP4 zoom animation

Install Poetry (recommended: `pipx`)

Make sure `.venv` is local

Exporting the `requirements.txt` file

`gmpy2` installation issues