tranzoom 1.0.0__py3-none-any.whl

tranzoom/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: Copyright 2026 <balparda@github.com> & <BellaKeri@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""TranZoom: Fractal manipulation with LLMs."""
+
+__all__: list[str] = ['__author__', '__version__']
+__version__ = '1.0.0'  # also update pyproject.toml
+__author__ = 'Daniel Balparda <balparda@github.com>, Bella Keri <BellaKeri@github.com>'

tranzoom/cli/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright 2026 <balparda@github.com> & <BellaKeri@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""CLI logic."""

tranzoom/cli/base.py

@@ -0,0 +1,153 @@
+# SPDX-FileCopyrightText: Copyright 2026 <balparda@github.com> & <BellaKeri@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""CLI: Base."""
+
+from __future__ import annotations
+
+import dataclasses
+import pathlib
+
+import typer
+from transcrypto.cli import clibase
+
+from tranzoom.core import fractal, frame, palette
+
+# global CLI data, and some test stuff
+
+# if `tests/data/images/demo-mandel-seahorse-tail.png` changes you have to update this hash!
+SEAHORSE_TAIL_HASH: str = '38824cdaa58b64496ebfd86facf4d4ba4596ab18db95ac97afd643a7a892ff83'
+# this is tested from `tests/cli/base_test.py` & `tests_integration/test_installed_cli.py`!
+
+# CLI options that can be re-used
+
+DEFAULT_IMAGE_PREFIX: str = 'mandel'
+
+# Image: output image
+IMAGE_WIDTH_OPTION: typer.models.OptionInfo = typer.Option(
+  frame.DEFAULT_IMAGE_SIZE,
+  '-w',
+  '--width',
+  min=frame.MIN_IMAGE_SIZE,
+  max=frame.MAX_IMAGE_SIZE,
+  help=(
+    f'Width of the image; {frame.MIN_IMAGE_SIZE} ≤ w ≤ {frame.MAX_IMAGE_SIZE}; '
+    f'default is {frame.DEFAULT_IMAGE_SIZE}'
+  ),
+)
+IMAGE_HEIGHT_OPTION: typer.models.OptionInfo = typer.Option(
+  frame.DEFAULT_IMAGE_SIZE,
+  '-h',
+  '--height',
+  min=frame.MIN_IMAGE_SIZE,
+  max=frame.MAX_IMAGE_SIZE,
+  help=(
+    f'Height of the image; {frame.MIN_IMAGE_SIZE} ≤ h ≤ {frame.MAX_IMAGE_SIZE}; '
+    f'default is {frame.DEFAULT_IMAGE_SIZE}'
+  ),
+)
+IMAGE_PATH_OUTPUT_OPTION: typer.models.OptionInfo = typer.Option(
+  None,
+  '-o',
+  '--out',
+  exists=True,
+  file_okay=False,
+  dir_okay=True,
+  readable=True,
+  writable=True,
+  help=(
+    'The local output root directory path, ex: "~/foo/bar/"; '
+    'if not given, the image will be saved in the current working directory'
+  ),
+)
+IMAGE_PREFIX_OPTION: typer.models.OptionInfo = typer.Option(
+  DEFAULT_IMAGE_PREFIX,
+  '--prefix',
+  help=(
+    f'Image save prefix; default: {DEFAULT_IMAGE_PREFIX!r} '
+    '(the final file name will be "<prefix>[-<date>][-<hash20>].png", note the date and the hash '
+    'can be turned off with --no-date and --no-hash, respectively)'
+  ),
+)
+IMAGE_INCLUDE_DATE_OPTION: typer.models.OptionInfo = typer.Option(
+  True,
+  '--date/--no-date',
+  help=(
+    'If True, file names will include the date-time as YYYYMMDDhhmmss; '
+    'if False, file names will not include the date-time; default is True'
+  ),
+)
+IMAGE_INCLUDE_HASH_OPTION: typer.models.OptionInfo = typer.Option(
+  True,
+  '--hash/--no-hash',
+  help=(
+    'If True, file names will include the hash; '
+    'if False, file names will not include the hash; default is True'
+  ),
+)
+
+# Frame: the default frame is the one that shows the whole Mandelbrot set, which is centered at
+# -0.75+0j and has width 2.5; the height is the same as the width by default;
+# The set <https://en.wikipedia.org/wiki/Mandelbrot_set> is contained in the rectangle with corners
+# -2.5-1.25j and 0.5+1.25j, which is exactly our default here
+FRAME_CENTER_RE_OPTION: typer.models.ArgumentInfo = typer.Argument(
+  frame.DEFAULT_FRAME_CENTER_RE,
+  help=f'Real part of the center point; default is {frame.DEFAULT_FRAME_CENTER_RE!r}',
+)
+FRAME_CENTER_IM_OPTION: typer.models.ArgumentInfo = typer.Argument(
+  frame.DEFAULT_FRAME_CENTER_IM,
+  help=f'Imaginary part of the center point; default is {frame.DEFAULT_FRAME_CENTER_IM!r}',
+)
+FRAME_WIDTH_OPTION: typer.models.ArgumentInfo = typer.Argument(
+  frame.DEFAULT_FRAME_SIZE,
+  help=f'Width of the frame in the real plane; default is {frame.DEFAULT_FRAME_SIZE!r}',
+)
+FRAME_HEIGHT_OPTION: typer.models.ArgumentInfo = typer.Argument(
+  None, help='Height of the frame in the imaginary plane; default is None, i.e, the same as width'
+)
+
+# Computation Options
+MAX_ITERATIONS_OPTION: typer.models.OptionInfo = typer.Option(
+  None,
+  '-i',
+  '--iter',
+  min=fractal.MIN_ITER,
+  max=fractal.MAX_ITER,
+  help=(
+    'Maximum iterations (depth) to compute before determining escape; '
+    f'{fractal.MIN_ITER} ≤ iter ≤ {fractal.MAX_ITER}; '
+    f'default is None (automatic search for optimal iterations --- recommended)'
+  ),
+)
+MAX_THREADS_OPTION: typer.models.OptionInfo = typer.Option(
+  None,
+  '--threads',
+  min=1,
+  max=fractal.MAX_CONCURRENCE,
+  help=(
+    'Number of threads to use for rendering; default is None, which means to use all available '
+    f'CPU cores; will be limited to {fractal.MAX_CONCURRENCE} threads'
+  ),
+)
+
+# Color options
+PALETTE_OPTION: typer.models.OptionInfo = typer.Option(
+  palette.DEFAULT_PALETTE,
+  '--palette',
+  help=(
+    f'Color palette to use for rendering; default is {palette.DEFAULT_PALETTE.value!r}; '
+    f'available palettes: {sorted(p.value for p in palette.PALETTES)}'
+  ),
+)
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
+class TranZoomConfig(clibase.CLIConfig):
+  """TranZoom global context, storing the configuration."""
+
+  img_width: int
+  img_height: int
+  img_output_path: pathlib.Path | None
+  img_use_date: bool
+  img_use_hash: bool
+  img_path_prefix: str
+  max_threads: int | None

tranzoom/cli/gencommand.py

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: Copyright 2026 <balparda@github.com> & <BellaKeri@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""CLI: Mandelbrot generation command.
+
+<https://en.wikipedia.org/wiki/Mandelbrot_set>
+
+README.md has good examples for different zoom levels.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import time
+
+import click
+from transcrypto.cli import clibase
+from transcrypto.utils import human, timer
+
+from tranzoom import mandel
+from tranzoom.cli import base
+from tranzoom.core import fractal, frame, image, palette
+
+
+@mandel.app.command(
+  'gen',
+  help='Generate a Mandelbrot image.',
+  epilog=(
+    'Examples:\n\n\n\n'
+    '$ poetry run mandel gen\n\n'
+    '1024x1024 Mandelbrot in frame [(-3/4, 0) @ 5/2] ...\n\n'
+    '...\n\n'
+    'Saved to "mandel-<date>-<hash>.png"\n\n\n\n'
+    '$ poetry run mandel -w 512 -h 512 gen " -0.74303" "0.126433" "0.01611"  '
+    '# note the space because of the "-"\n\n'
+    '<saves Mandelbrot to disk with center --0.74303+0.126433j and width 0.01611>'
+  ),
+)
+@clibase.CLIErrorGuard
+def Gen(  # documentation is help/epilog/args  # noqa: D103
+  *,
+  ctx: click.Context,
+  center_re: str = base.FRAME_CENTER_RE_OPTION,  # type: ignore[assignment]
+  center_im: str = base.FRAME_CENTER_IM_OPTION,  # type: ignore[assignment]
+  f_width: str = base.FRAME_WIDTH_OPTION,  # type: ignore[assignment]
+  f_height: str | None = base.FRAME_HEIGHT_OPTION,  # type: ignore[assignment]
+  max_iter: int | None = base.MAX_ITERATIONS_OPTION,  # type: ignore[assignment]
+  pal: palette.Palette = base.PALETTE_OPTION,  # type: ignore[assignment]
+) -> None:
+  # check sanity
+  config: base.TranZoomConfig = ctx.obj
+  try:
+    frm: frame.Frame = frame.Frame.FromCenter(center_re, center_im, f_width, f_height)
+  except Exception as err:
+    raise click.UsageError(
+      f'Invalid coordinates: {center_re=}, {center_im=}, {f_width=}, {f_height=}'
+    ) from err
+  magnification, magnitude = frm.magnification
+  magnification_str: str = (
+    # beyond 10^21, human-readable formatting becomes ridiculous, so we use scientific notation
+    human.HumanizedDecimal(float(magnification)) if magnitude < 21 else f'{magnification:e}'  # noqa: PLR2004
+  )
+  config.console.print(
+    f'\n{config.img_width}x{config.img_height} Mandelbrot in frame {frm}, '
+    f'precision {frm.precision} bits, {magnification_str} magnification, '
+    f'{"AUTO" if max_iter is None else max_iter} iterations...\n'
+  )
+  # render the image
+  with timer.Timer(emit_log=False) as tmr:
+    img: image.Image = fractal.Mandelbrot(
+      frm, config.img_width, config.img_height, max_iter=max_iter, n_processes=config.max_threads
+    )
+    raw_png, raw_hash = img.AsPNG(pal=pal)
+  config.console.print(f'\nGenerated image {raw_hash!r} in {tmr}, escape range {img.escape_range}')
+  # check we can recover the hash from the PNG: should never fail unless we have a bug
+  w, h, png_hash, _ = image.GetBasicDataFromPNG(raw_png)
+  if png_hash != raw_hash or w != config.img_width or h != config.img_height:
+    raise click.ClickException(
+      f'Mismatch: expected {config.img_width}x{config.img_height}/{raw_hash!r} but '
+      f'got {w}x{h}/{png_hash!r} from PNG; this should never happen, please report this as a bug'
+    )
+  # save the image to a file named by its time/hash
+  tm_str: str = time.strftime('%Y%m%d%H%M%S', time.gmtime(timer.Now()))
+  # validate that img_path_prefix is a basename (no path separators) to prevent directory traversal
+  filename: str = config.img_path_prefix
+  if pathlib.Path(filename).name != config.img_path_prefix:
+    raise click.UsageError(
+      f'Invalid prefix: {config.img_path_prefix!r} has path separators (ex: "/" or "\\")'
+    )
+  # add date and hash to the file name if requested
+  if config.img_use_date:
+    filename += f'-{tm_str}'
+  if config.img_use_hash:
+    # use 20 chars of the hash to avoid very long file names; 20 chars = 10 bytes = 80 bits;
+    # collision is 1 in 2**40 ~ 1 in 1 trillion, which is good enough for our use case
+    filename += f'-{raw_hash[:20]}'
+  # add .png extension, make full path, and save the file
+  filename += '.png'
+  full_path: pathlib.Path = (
+    pathlib.Path(filename) if config.img_output_path is None else config.img_output_path / filename
+  )
+  full_path.write_bytes(raw_png)
+  config.console.print(f'Saved to "{full_path}"\n')

tranzoom/core/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright 2026 <balparda@github.com> & <BellaKeri@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Core business logic."""

tranzoom/core/fractal.py

@@ -0,0 +1,337 @@
+# SPDX-FileCopyrightText: Copyright 2026 <balparda@github.com> & <BellaKeri@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Fractal computing.
+
+Heavy use of gmpy2 for arbitrary precision, which is needed to render deep zooms correctly; see
+<https://gmpy2.readthedocs.io/en/latest/>
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import logging
+import os
+from concurrent import futures
+from typing import NoReturn
+
+import gmpy2
+import tqdm
+
+from tranzoom.core import frame, image
+
+# iteration constants
+
+MIN_ITER: int = 1000
+DEFAULT_ITER: int = 1000
+HIGH_ITERS: list[int] = [100_000, 1_000_000, 10_000_000]  # these are very high iteration counts
+MAX_ITER: int = 2 ** (image.N_BYTES_UINT * 8) - 1  # 4_294_967_295, max value for array('I'), uint32
+
+# automated search for iter
+
+_ITER_SAFETY_FACTOR: float = 1.5  # we multiply the estimated iter by this to be safe
+
+# multiprocessing
+
+AVAILABLE_CPU: int = int(getattr(os, 'process_cpu_count', os.cpu_count)() or 1)
+_MAX_PRE_PROCESS_CONCURRENCE: int = 4  # for the preprocess step, we limit the concurrency
+MAX_CONCURRENCE: int = 16  # for the main rendering step, we limit the concurrency
+
+# gmpy2.mpfr constants
+_MPFR_ZERO = gmpy2.mpfr('0')
+_MPFR_SIXTEENTH = gmpy2.mpfr('0.0625')
+_MPFR_FOURTH = gmpy2.mpfr('0.25')
+_MPFR_ONE = gmpy2.mpfr('1')
+_MPFR_TWO = gmpy2.mpfr('2')
+_MPFR_FOUR = gmpy2.mpfr('4')
+
+
+class Error(image.Error):
+  """Base fractal exception."""
+
+
+def Mandelbrot(
+  frm: frame.Frame,
+  width: int,
+  height: int,
+  *,
+  max_iter: int | None = None,
+  progress_bar: bool = True,
+  n_processes: int | None = None,
+) -> image.Image:
+  """Render the frame rectangle to an Image.
+
+  Args:
+    frm (Frame): The frame to render.
+    width (int): The width of the output image in pixels.
+    height (int): The height of the output image in pixels.
+    max_iter (int | None, optional): The maximum number of iterations to determine escape.
+        Defaults to None, and that means "auto".
+    progress_bar (bool, optional): Whether to show a progress bar. Defaults to True.
+    n_processes (int | None, optional): The number of processes to use for rendering. Defaults
+        to None, which means to use all available CPU cores. Will be limited to MAX_CONCURRENCE.
+
+  Returns:
+    image.Image: The rendered fractal image.
+
+  Raises:
+    Error: on error
+
+  """
+  if n_processes is not None and n_processes < 1:
+    raise Error(f'{n_processes=} must be a positive integer or None')
+  # if max_iter is None, we do an adaptive iteration limit calculation based on a small test render
+  # BEWARE: the method call will call Mandelbrot() recursively, but with a fixed max_iter!
+  max_iter = _MandelbrotAdaptiveIterations(frm, progress_bar) if max_iter is None else max_iter
+  # determine processes
+  is_preprocess: bool = width == frame.MIN_IMAGE_SIZE and height == frame.MIN_IMAGE_SIZE
+  n_processes = n_processes or AVAILABLE_CPU
+  n_processes = min(n_processes, _MAX_PRE_PROCESS_CONCURRENCE) if is_preprocess else n_processes
+  n_processes = min(n_processes, MAX_CONCURRENCE, AVAILABLE_CPU)  # never exceed CPU!
+  logging.debug(
+    f'Mandelbrot using {n_processes} process(es) for {"PRE " if is_preprocess else ""}rendering'
+  )
+  # create inputs
+  inp: list[MandelbrotTaskInput] = [
+    MandelbrotTaskInput(
+      frm=frm,
+      width=width,
+      height=height,
+      max_iter=max_iter,
+      progress_bar=progress_bar,
+      n_task=i + 1,
+      total_tasks=n_processes,
+    )
+    for i in range(n_processes)
+  ]
+  # execute in processes
+  results: list[MandelbrotTaskOutput]
+  if n_processes == 1:
+    # no multiprocessing, just run the single task directly in this process (also good for debug)
+    results = [_MandelbrotComputation(inp[0])]
+  else:
+    # multiprocessing: run the tasks in separate processes and collect results
+    with futures.ProcessPoolExecutor(max_workers=n_processes) as executor:
+      results = list(executor.map(_MandelbrotComputation, inp))
+  # at this point all tasks are finished: check we have them all!
+  if len(results) != n_processes:
+    raise Error(f'Expected {n_processes} results from Mandelbrot computations, got {len(results)}')
+  img: image.Image = results[0].img  # start with the first image to save time and space
+  if n_processes > 1:
+    # combine results into a single image; possible b/c each task wrote to a disjoint set of pixels
+    for result in results[1:]:
+      # copy only this task's interleaved pixels into the final image
+      n_task: int = result.n_task - 1  # convert to 0-based index for stepped slice indexing
+      img.escape[n_task::n_processes] = result.img.escape[n_task::n_processes]
+  # all copied, so we can return the final image
+  return img
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
+class MandelbrotTaskInput:
+  """Defines a Mandelbrot task."""
+
+  frm: frame.Frame
+  width: int
+  height: int
+  max_iter: int
+  progress_bar: bool
+  n_task: int
+  total_tasks: int
+
+  def __post_init__(self) -> None:
+    """Validate parameters.
+
+    Raises:
+      Error: on error
+
+    """
+    # check size
+    if not (frame.MIN_IMAGE_SIZE <= self.width <= frame.MAX_IMAGE_SIZE) or not (
+      frame.MIN_IMAGE_SIZE <= self.height <= frame.MAX_IMAGE_SIZE
+    ):
+      raise Error(
+        f'{self.width=} and {self.height=} must be between '
+        f'{frame.MIN_IMAGE_SIZE} and {frame.MAX_IMAGE_SIZE}'
+      )
+    # sanity check iter_limit: if error, it came from the user (b/c adaptive clamps to the limits)
+    if not (MIN_ITER <= self.max_iter <= MAX_ITER):
+      raise Error(f'{self.max_iter=} must be between {MIN_ITER} and {MAX_ITER}')
+    # check task numbers
+    if not (1 <= self.n_task <= self.total_tasks):
+      raise Error(f'{self.n_task=} must be between 1 and {self.total_tasks}')
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
+class MandelbrotTaskOutput:
+  """Defines a Mandelbrot task output."""
+
+  img: image.Image
+  n_task: int
+  total_tasks: int
+
+
+def _MandelbrotComputation(inp: MandelbrotTaskInput) -> MandelbrotTaskOutput:  # noqa: PLR0914
+  """Compute the Mandelbrot image for the given task input. ONE THREAD FOR MULTIPROCESSING.
+
+  Args:
+    inp (MandelbrotTaskInput): The task input containing all parameters for the computation.
+
+  Returns:
+    MandelbrotTaskOutput: The rendered fractal image and task information.
+
+  Raises:
+    Error: on error
+
+  """
+  is_preprocess: bool = inp.width == frame.MIN_IMAGE_SIZE and inp.height == frame.MIN_IMAGE_SIZE
+  # create image; will also check the parameters and frame validity in the Image constructor
+  img: image.Image = image.Image(inp.frm, inp.width, inp.height)
+  # compute pixel size in complex plane and check frame validity; exact computation (gmpy2.mpq)
+  dx: gmpy2.mpq
+  dy: gmpy2.mpq
+  dx, dy = inp.frm.size
+  dx, dy = dx / gmpy2.mpq(inp.width - 1), dy / gmpy2.mpq(inp.height - 1)
+  if dx <= 0 or dy <= 0:
+    raise Error(f'frame must have positive area, got {dx=} and {dy=}, should never happen')
+  # start the mpfr context for floating-point computations with the precision needed
+  with inp.frm.context:
+    # precompute x coordinates once: this matters because mpfr construction and arithmetic
+    # are relatively expensive and we can reuse the x values across rows ("inner for loop");
+    # also, this is where the "X" (real) coordinates are converted mpq->mpfr
+    xs: list[gmpy2.mpfr] = [
+      gmpy2.mpfr(inp.frm.top_re + gmpy2.mpq(i) * dx) for i in range(inp.width)
+    ]
+    # create progress bar based on total pixels and the options
+    has_procs: bool = inp.total_tasks > 1
+    n_task: int = inp.n_task - 1  # convert to 0-based index for easier modulo math
+    p_bar: tqdm.tqdm[NoReturn] = tqdm.tqdm(
+      total=inp.width * inp.height,
+      desc='Pre' if is_preprocess else 'Img',
+      unit='px',
+      dynamic_ncols=True,
+      smoothing=0.1,
+      colour='green',
+      disable=not inp.progress_bar or (has_procs and n_task != 0),  # show for the 1st process only
+    )
+    # iterate over pixels in row-major order, computing escape iterations in mpfr
+    px_count: int = -1
+    for py in range(inp.height):
+      # PILImage.frombytes interprets the first row written as the top row of the image, so
+      # we iterate y inverted by starting at the top and going down;
+      # this is the "outer for loop", no benefit in pre-computing y values;
+      # also, this is where the "Y" (imaginary) coordinates are converted mpq->mpfr
+      cy: gmpy2.mpfr = gmpy2.mpfr(inp.frm.top_im - gmpy2.mpq(py) * dy)
+      # iterate over columns, reusing x values and doing the escape test in mpfr for correctness
+      for px in range(inp.width):
+        px_count += 1
+        if has_procs and (px_count % inp.total_tasks) != n_task:
+          # this pixel is not for this process, skip it but still update the progress bar
+          p_bar.update(1)
+          continue
+        # either this is a solo process, or this pixel is for this process
+        cx: gmpy2.mpfr = xs[px]
+        # fast interior tests, all in mpfr: main cardioid and period-2 bulb.
+        x_minus_quarter: gmpy2.mpfr = cx - _MPFR_FOURTH
+        q: gmpy2.mpfr = x_minus_quarter * x_minus_quarter + cy * cy
+        in_cardioid: bool = q * (q + x_minus_quarter) <= _MPFR_FOURTH * cy * cy
+        x_plus_one: gmpy2.mpfr = cx + _MPFR_ONE
+        in_bulb: bool = x_plus_one * x_plus_one + cy * cy <= _MPFR_SIXTEENTH
+        if in_cardioid or in_bulb:
+          # point is in the main cardioid or period-2 bulb, so it's an interior point, no escape
+          img.escape[px_count] = inp.max_iter  # carefully set this directly in the array
+          p_bar.update(1)  # we touched a pixel, so update the progress bar
+          continue
+        # not in the main cardioid or period-2 bulb, do the full escape-time test in mpfr
+        zx: gmpy2.mpfr = _MPFR_ZERO
+        zy: gmpy2.mpfr = _MPFR_ZERO
+        escaped_at: int = 0
+        # escape-time loop, implemented with explicit zx/zy variables
+        for escaped_at in range(inp.max_iter):  # noqa: B007
+          zx2: gmpy2.mpfr = zx * zx
+          zy2: gmpy2.mpfr = zy * zy
+          # avoid sqrt(abs(z)); compare squared magnitude to 2^2
+          if zx2 + zy2 > _MPFR_FOUR:
+            break
+          # z = z^2 + c in terms of zx/zy: zx' = zx^2 - zy^2 + cx
+          zy = _MPFR_TWO * zx * zy + cy
+          zx = zx2 - zy2 + cx
+        else:
+          escaped_at = inp.max_iter  # if we didn't break, we reached max_iter, mark as non-escaped
+        img.escape[px_count] = escaped_at  # carefully set this directly in the array
+        p_bar.update(1)  # we touched a pixel, so update the progress bar
+  # done
+  p_bar.close()
+  img.SetDepth(inp.max_iter)  # set the depth of the image to the max_iter we used
+  return MandelbrotTaskOutput(img=img, n_task=inp.n_task, total_tasks=inp.total_tasks)
+
+
+def _MandelbrotAdaptiveIterations(frm: frame.Frame, progress_bar: bool) -> int:
+  """Estimate a suitable max_iter for the full image by rendering a small test image.
+
+  Current algorithm:
+  - Render a very small image (MIN_IMAGE_SIZE x MIN_IMAGE_SIZE) with a very high iteration limit
+    (HIGH_ITERS, starting with 100k and going up to 10M if needed).
+  - Build a histogram of escape iterations for the small image, and find the highest escape
+    iteration that is below the high iteration limit.
+  - Multiply that escape iteration by a safety factor _ITER_SAFETY_FACTOR to get the estimated
+    max_iter for the full image.
+  - If the estimated max_iter is above the high iteration limit, try again with a higher
+    high iteration limit from HIGH_ITERS.
+  - If we exhaust all high iteration limits in HIGH_ITERS without finding a suitable max_iter,
+    raise an Error.
+
+  Args:
+    frm (Frame): The frame to render.
+    progress_bar (bool): Whether to show a progress bar during the test render.
+
+  Returns:
+    int: The estimated max_iter for the full image, based on the escape histogram of the test render
+
+  Raises:
+    Error: if the estimated max_iter exceeds the adaptive limit
+
+  """
+  max_iter: int = MAX_ITER
+  for high_iter in HIGH_ITERS:
+    # make the smallest image
+    img16: image.Image = Mandelbrot(
+      frm,
+      frame.MIN_IMAGE_SIZE,
+      frame.MIN_IMAGE_SIZE,
+      max_iter=high_iter,
+      progress_bar=progress_bar,
+    )
+    # estimate the needed iterations for the full image based on the smallest image;
+    # make the histogram of escape iterations for the smallest image, and find the highest escape
+    escape_histogram: dict[int, int] = {}
+    for escaped_at in img16.escape:
+      escape_histogram[escaped_at] = escape_histogram.get(escaped_at, 0) + 1
+    # sort the histogram by escape iteration; find the highest escape iteration that < high limit
+    # if all pixels hit high_iter then max_iter will be high_iter, and we WANT it to FAIL
+    histogram: list[tuple[int, int]] = sorted(escape_histogram.items())
+    max_iter = (
+      histogram[-1][0] if histogram[-1][0] != high_iter or len(histogram) == 1 else histogram[-2][0]
+    )
+    # apply safety factor and clamp
+    max_iter = min(MAX_ITER, max(MIN_ITER, int(max_iter * _ITER_SAFETY_FACTOR)))
+    if max_iter < high_iter:
+      # we found a winner!
+      if len(histogram) > 7:  # noqa: PLR2004 ; 7 is 3 before, the middle, and 3 after
+        # this is usually the case: many escape values, so summarize the middle ones
+        summary_histogram: list[tuple[int, int] | tuple[str, int]] = [
+          *histogram[:3],
+          ('...', sum(count for _, count in histogram[3:-3])),
+          *histogram[-3:],
+        ]
+        logging.warning(f'Picked {max_iter=}: histogram {summary_histogram}')
+      else:
+        # probably a pretty rare thing, but then we can show all
+        logging.warning(f'Picked {max_iter=}: histogram {histogram}')
+      # stop here
+      return max_iter
+    # here we didn't find, so we loop to the next higher limit...
+  # if we exhausted all the high_iters without finding a suitable max_iter, we have to give up
+  raise Error(
+    f'Estimated {max_iter=} is above the adaptive limit of {HIGH_ITERS[-1]}; '
+    'maybe this frame is interior-only (all pixels are non-escaping)'
+  )