stippler 0.2.0.0__py3-none-any.whl

stippler/__init__.py

@@ -0,0 +1,54 @@
+"""Hand-drawn weighted Voronoi stippling.
+
+Grayscale image -> stipple geometry/output, with controls for early-stopped
+relaxation, varying dot size, positional jitter, imperfect dot edges and
+contrast (gamma). Optional Lu et al. scientific-illustration enhancements
+(boundary/silhouette density, interior sparsity, lighting, depth, silhouette
+curves) are toggled via :class:`IllustrationParams`. Targets Python 3.9.10 for
+Rhino 8 CPython compatibility.
+
+The high-level entry point is :func:`stipple`, which returns a
+:class:`StippleResult` carrying the points, radii, per-dot polygons and
+optional silhouette curves. Render helpers (:func:`render_matplotlib`,
+:func:`render_svg`, :func:`save_points`) turn that into files.
+"""
+from . import voronoi
+from .illustration import IllustrationParams
+from .pipeline import (
+    StippleResult,
+    stipple,
+    load_density,
+    prepare_density,
+    normalize,
+    initialization,
+    relax,
+    assign_radii,
+    apply_position_jitter,
+    dot_polygons,
+    render_matplotlib,
+    render_svg,
+    save_points,
+    main,
+)
+
+__version__ = "0.2.0.0"
+
+__all__ = [
+    "StippleResult",
+    "stipple",
+    "IllustrationParams",
+    "load_density",
+    "prepare_density",
+    "normalize",
+    "initialization",
+    "relax",
+    "assign_radii",
+    "apply_position_jitter",
+    "dot_polygons",
+    "render_matplotlib",
+    "render_svg",
+    "save_points",
+    "main",
+    "voronoi",
+    "__version__",
+]

stippler/classic.py

@@ -0,0 +1,278 @@
+#! /usr/bin/env python3
+# -----------------------------------------------------------------------------
+# Weighted Voronoi Stippler
+# Copyright (2017) Nicolas P. Rougier - BSD license
+#
+# Implementation of:
+#   Weighted Voronoi Stippling, Adrian Secord
+#   Symposium on Non-Photorealistic Animation and Rendering (NPAR), 2002
+# -----------------------------------------------------------------------------
+# Some usage examples
+#
+# stippler.py boots.jpg --save --force --n_point 20000 --n_iter 50
+#                       --pointsize 0.5 2.5 --figsize 8 --interactive
+# stippler.py plant.png --save --force --n_point 20000 --n_iter 50
+#                       --pointsize 0.5 1.5 --figsize 8
+# stippler.py gradient.png --save --force --n_point 5000 --n_iter 50
+#                          --pointsize 1.0 1.0 --figsize 6
+# -----------------------------------------------------------------------------
+# usage: stippler.py [-h] [--n_iter n] [--n_point n] [--epsilon n]
+#                    [--pointsize min,max) (min,max] [--figsize w,h] [--force]
+#                    [--save] [--display] [--interactive]
+#                    image filename
+#
+# Weighted Vororonoi Stippler
+#
+# positional arguments:
+#   image filename        Density image filename
+#
+# optional arguments:
+#   -h, --help            show this help message and exit
+#   --n_iter n            Maximum number of iterations
+#   --n_point n           Number of points
+#   --epsilon n           Early stop criterion
+#   --pointsize (min,max) (min,max)
+#                         Point mix/max size for final display
+#   --figsize w,h         Figure size
+#   --force               Force recomputation
+#   --save                Save computed points
+#   --display             Display final result
+#   --interactive         Display intermediate results (slower)
+# -----------------------------------------------------------------------------
+import tqdm
+import os.path
+import numpy as np
+import scipy.ndimage
+from PIL import Image
+
+try:
+    from . import voronoi
+except ImportError:  # allow running the file directly (python classic.py)
+    import voronoi
+
+
+def imread(filename):
+    """Load an image as a 2D float grayscale array.
+
+    Replaces the removed ``scipy.misc.imread(..., flatten=True, mode='L')``
+    so the code runs on modern SciPy / Python 3.9.10 (Rhino CPython runtime).
+    """
+    img = Image.open(filename).convert("L")
+    return np.asarray(img, dtype=np.float64)
+
+
+def normalize(D):
+    Vmin, Vmax = D.min(), D.max()
+    if Vmax - Vmin > 1e-5:
+        D = (D-Vmin)/(Vmax-Vmin)
+    else:
+        D = np.zeros_like(D)
+    return D
+
+
+def initialization(n, D):
+    """
+    Return n points distributed over [xmin, xmax] x [ymin, ymax]
+    according to (normalized) density distribution.
+
+    with xmin, xmax = 0, density.shape[1]
+         ymin, ymax = 0, density.shape[0]
+
+    The algorithm here is a simple rejection sampling.
+    """
+
+    samples = []
+    while len(samples) < n:
+        # X = np.random.randint(0, D.shape[1], 10*n)
+        # Y = np.random.randint(0, D.shape[0], 10*n)
+        X = np.random.uniform(0, D.shape[1], 10*n)
+        Y = np.random.uniform(0, D.shape[0], 10*n)
+        P = np.random.uniform(0, 1, 10*n)
+        index = 0
+        while index < len(X) and len(samples) < n:
+            x, y = X[index], Y[index]
+            x_, y_ = int(np.floor(x)), int(np.floor(y))
+            if P[index] < D[y_, x_]:
+                samples.append([x, y])
+            index += 1
+    return np.array(samples)
+
+
+if __name__ == '__main__':
+    import argparse
+    import matplotlib.pyplot as plt
+    from matplotlib.animation import FuncAnimation
+
+    default = {
+        "n_point": 5000,
+        "n_iter": 50,
+        "threshold": 255,
+        "force": False,
+        "save": False,
+        "figsize": 6,
+        "display": False,
+        "interactive": False,
+        "pointsize": (1.0, 1.0),
+    }
+
+    description = "Weighted Vororonoi Stippler"
+    parser = argparse.ArgumentParser(description=description)
+    parser.add_argument('filename', metavar='image filename', type=str,
+                        help='Density image filename ')
+    parser.add_argument('--n_iter', metavar='n', type=int,
+                        default=default["n_iter"],
+                        help='Maximum number of iterations')
+    parser.add_argument('--n_point', metavar='n', type=int,
+                        default=default["n_point"],
+                        help='Number of points')
+    parser.add_argument('--pointsize', metavar='(min,max)', type=float,
+                        nargs=2, default=default["pointsize"],
+                        help='Point mix/max size for final display')
+    parser.add_argument('--figsize', metavar='w,h', type=int,
+                        default=default["figsize"],
+                        help='Figure size')
+    parser.add_argument('--force', action='store_true',
+                        default=default["force"],
+                        help='Force recomputation')
+    parser.add_argument('--threshold', metavar='n', type=int,
+                        default=default["threshold"],
+                        help='Grey level threshold')
+    parser.add_argument('--save', action='store_true',
+                        default=default["save"],
+                        help='Save computed points')
+    parser.add_argument('--display', action='store_true',
+                        default=default["display"],
+                        help='Display final result')
+    parser.add_argument('--interactive', action='store_true',
+                        default=default["interactive"],
+                        help='Display intermediate results (slower)')
+    args = parser.parse_args()
+
+    filename = args.filename
+    density = imread(filename)
+
+    # We want (approximately) 500 pixels per voronoi region
+    zoom = (args.n_point * 500) / (density.shape[0]*density.shape[1])
+    zoom = int(round(np.sqrt(zoom)))
+    density = scipy.ndimage.zoom(density, zoom, order=0)
+    # Apply threshold onto image
+    # Any color > threshold will be white
+    density = np.minimum(density, args.threshold)
+
+    density = 1.0 - normalize(density)
+    density = density[::-1, :]
+    density_P = density.cumsum(axis=1)
+    density_Q = density_P.cumsum(axis=1)
+
+    dirname = os.path.dirname(filename)
+    basename = (os.path.basename(filename).split('.'))[0]
+    pdf_filename = os.path.join(dirname, basename + "-stipple.pdf")
+    png_filename = os.path.join(dirname, basename + "-stipple.png")
+    dat_filename = os.path.join(dirname, basename + "-stipple.npy")
+
+    # Initialization
+    if not os.path.exists(dat_filename) or args.force:
+        points = initialization(args.n_point, density)
+        print("Nb points:", args.n_point)
+        print("Nb iterations:", args.n_iter)
+    else:
+        points = np.load(dat_filename)
+        print("Nb points:", len(points))
+        print("Nb iterations: -")
+    print("Density file: %s (resized to %dx%d)" % (
+          filename, density.shape[1], density.shape[0]))
+    print("Output file (PDF): %s " % pdf_filename)
+    print("            (PNG): %s " % png_filename)
+    print("            (DAT): %s " % dat_filename)
+
+    xmin, xmax = 0, density.shape[1]
+    ymin, ymax = 0, density.shape[0]
+    bbox = np.array([xmin, xmax, ymin, ymax])
+    ratio = (xmax-xmin)/(ymax-ymin)
+
+    # Interactive display
+    if args.interactive:
+
+        # Setup figure
+        fig = plt.figure(figsize=(args.figsize, args.figsize/ratio),
+                         facecolor="white")
+        ax = fig.add_axes([0, 0, 1, 1], frameon=False)
+        ax.set_xlim([xmin, xmax])
+        ax.set_xticks([])
+        ax.set_ylim([ymin, ymax])
+        ax.set_yticks([])
+        scatter = ax.scatter(points[:, 0], points[:, 1], s=1,
+                             facecolor="k", edgecolor="None")
+
+        def update(frame):
+            global points
+            # Recompute weighted centroids
+            regions, points = voronoi.centroids(
+                points,
+                density,
+                density_P,
+                density_Q
+            )
+
+            # Update figure
+            Pi = points.astype(int)
+            X = np.maximum(np.minimum(Pi[:, 0], density.shape[1]-1), 0)
+            Y = np.maximum(np.minimum(Pi[:, 1], density.shape[0]-1), 0)
+            sizes = (args.pointsize[0] +
+                     (args.pointsize[1]-args.pointsize[0])*density[Y, X])
+            scatter.set_offsets(points)
+            scatter.set_sizes(sizes)
+            bar.update()
+
+            # Save result at last frame
+            if (frame == args.n_iter-2 and
+                    (not os.path.exists(dat_filename) or args.save)):
+                np.save(dat_filename, points)
+                plt.savefig(pdf_filename)
+                plt.savefig(png_filename)
+
+        bar = tqdm.tqdm(total=args.n_iter)
+        animation = FuncAnimation(fig, update,
+                                  repeat=False, frames=args.n_iter-1)
+        plt.show()
+
+    elif not os.path.exists(dat_filename) or args.force:
+        for i in tqdm.trange(args.n_iter):
+            regions, points = voronoi.centroids(
+                points,
+                density,
+                density_P,
+                density_Q
+            )
+
+    if (args.save or args.display) and not args.interactive:
+        fig = plt.figure(figsize=(args.figsize, args.figsize/ratio),
+                         facecolor="white")
+        ax = fig.add_axes([0, 0, 1, 1], frameon=False)
+        ax.set_xlim([xmin, xmax])
+        ax.set_xticks([])
+        ax.set_ylim([ymin, ymax])
+        ax.set_yticks([])
+        scatter = ax.scatter(points[:, 0], points[:, 1], s=1,
+                             facecolor="k", edgecolor="None")
+        Pi = points.astype(int)
+        X = np.maximum(np.minimum(Pi[:, 0], density.shape[1]-1), 0)
+        Y = np.maximum(np.minimum(Pi[:, 1], density.shape[0]-1), 0)
+        sizes = (args.pointsize[0] +
+                 (args.pointsize[1]-args.pointsize[0])*density[Y, X])
+        scatter.set_offsets(points)
+        scatter.set_sizes(sizes)
+
+        # Save stipple points and tippled image
+        if not os.path.exists(dat_filename) or args.save:
+            np.save(dat_filename, points)
+            plt.savefig(pdf_filename)
+            plt.savefig(png_filename)
+
+        if args.display:
+            plt.show()
+
+    # Plot voronoi regions if you want
+    # for region in vor.filtered_regions:
+    #     vertices = vor.vertices[region, :]
+    #     ax.plot(vertices[:, 0], vertices[:, 1], linewidth=.5, color='.5' )

stippler/illustration.py

@@ -0,0 +1,311 @@
+#! /usr/bin/env python3
+# -----------------------------------------------------------------------------
+# Scientific-illustration density and silhouette-curve helpers.
+#
+# Optional enhancements adapted from Lu et al., "Non-Photorealistic Volume
+# Rendering Using Stippling Techniques" (vis_stipple.pdf). Each feature is
+# independently toggled via :class:`IllustrationParams`.
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import numpy as np
+import scipy.ndimage
+from PIL import Image
+
+
+def _unit3(v):
+    v = np.asarray(v, dtype=np.float64)
+    n = np.linalg.norm(v)
+    if n < 1e-12:
+        return np.array([0.0, 0.0, 1.0])
+    return v / n
+
+
+def _normalize01(field):
+    lo, hi = float(field.min()), float(field.max())
+    if hi - lo > 1e-8:
+        return (field - lo) / (hi - lo)
+    return np.zeros_like(field)
+
+
+class IllustrationParams(object):
+    """Optional Lu et al. illustration controls (all off by default)."""
+
+    def __init__(
+        self,
+        boundary=False,
+        boundary_kgc=0.4,
+        boundary_kgs=0.5,
+        boundary_kge=1.0,
+        silhouette_density=False,
+        silhouette_ksc=0.3,
+        silhouette_kss=0.5,
+        silhouette_kse=1.0,
+        interior=False,
+        interior_kte=0.5,
+        lighting=False,
+        light=(1.0, 1.0, 1.0),
+        lighting_kle=2.0,
+        depth=False,
+        depth_kde=1.0,
+        gradient_sigma=1.0,
+        gradient_size=False,
+        gradient_size_strength=1.0,
+        silhouette_curves=False,
+        curve_threshold_log=0.12,
+        curve_threshold_eye=0.35,
+        curve_threshold_grad=0.2,
+        curve_length=3.0,
+        curve_stride=2,
+        view=(0.0, 0.0, 1.0),
+    ):
+        self.boundary = boundary
+        self.boundary_kgc = boundary_kgc
+        self.boundary_kgs = boundary_kgs
+        self.boundary_kge = boundary_kge
+        self.silhouette_density = silhouette_density
+        self.silhouette_ksc = silhouette_ksc
+        self.silhouette_kss = silhouette_kss
+        self.silhouette_kse = silhouette_kse
+        self.interior = interior
+        self.interior_kte = interior_kte
+        self.lighting = lighting
+        self.light = _unit3(light)
+        self.lighting_kle = lighting_kle
+        self.depth = depth
+        self.depth_kde = depth_kde
+        self.gradient_sigma = gradient_sigma
+        self.gradient_size = gradient_size
+        self.gradient_size_strength = gradient_size_strength
+        self.silhouette_curves = silhouette_curves
+        self.curve_threshold_log = curve_threshold_log
+        self.curve_threshold_eye = curve_threshold_eye
+        self.curve_threshold_grad = curve_threshold_grad
+        self.curve_length = curve_length
+        self.curve_stride = max(1, int(curve_stride))
+        self.view = _unit3(view)
+
+    @property
+    def active(self):
+        return (
+            self.boundary
+            or self.silhouette_density
+            or self.interior
+            or self.lighting
+            or self.depth
+            or self.gradient_size
+            or self.silhouette_curves
+        )
+
+
+def load_aux_map(filename, target_shape, mode="L"):
+    """Load and resize an auxiliary image to ``target_shape`` (H, W)."""
+    img = Image.open(filename)
+    if mode == "RGB":
+        img = img.convert("RGB")
+    else:
+        img = img.convert("L")
+    arr = np.asarray(img, dtype=np.float64)
+    if arr.shape[:2] != target_shape:
+        zoom_y = target_shape[0] / arr.shape[0]
+        zoom_x = target_shape[1] / arr.shape[1]
+        if mode == "RGB":
+            arr = scipy.ndimage.zoom(arr, (zoom_y, zoom_x, 1.0), order=1)
+        else:
+            arr = scipy.ndimage.zoom(arr, zoom_y, order=1)
+    return arr
+
+
+def normals_from_rgb(rgb):
+    """Decode an RGB normal map (0–255) into unit normals (H, W, 3)."""
+    n = rgb / 127.5 - 1.0
+    length = np.linalg.norm(n, axis=-1, keepdims=True)
+    length = np.maximum(length, 1e-8)
+    return n / length
+
+
+def normals_from_gradient(gx, gy):
+    """Infer approximate normals from a 2D tone gradient (H, W)."""
+    nx = -gx
+    ny = -gy
+    nz = np.sqrt(np.maximum(1.0 - np.clip(nx * nx + ny * ny, 0.0, 1.0), 0.0))
+    n = np.stack([nx, ny, nz], axis=-1)
+    length = np.linalg.norm(n, axis=-1, keepdims=True)
+    length = np.maximum(length, 1e-8)
+    return n / length
+
+
+def compute_image_gradient(field, sigma=1.0):
+    """Return smoothed ``(gx, gy, magnitude)`` for a tone/density field."""
+    work = field
+    if sigma > 0:
+        work = scipy.ndimage.gaussian_filter(field, sigma)
+    gy, gx = np.gradient(work)
+    mag = np.hypot(gx, gy)
+    return gx, gy, _normalize01(mag)
+
+
+def compute_log(field, sigma=1.0):
+    """Laplacian-of-Gaussian response (used for silhouette-curve detection)."""
+    blurred = (
+        scipy.ndimage.gaussian_filter(field, sigma)
+        if sigma > 0
+        else field
+    )
+    return scipy.ndimage.laplace(blurred)
+
+
+def resolve_normals(tone, gx, gy, normal_map_rgb=None):
+    """Return unit normals, using a normal map when provided."""
+    if normal_map_rgb is not None:
+        return normals_from_rgb(normal_map_rgb)
+    return normals_from_gradient(gx, gy)
+
+
+def boundary_factor(tone, grad_mag, kgc, kgs, kge):
+    """Lu et al. boundary emphasis (Eq. 5), normalized to [0, 1]."""
+    raw = tone * (kgc + kgs * np.power(grad_mag, kge))
+    return _normalize01(raw)
+
+
+def silhouette_factor(tone, silhouette_strength, ksc, kss, kse):
+    """Lu et al. silhouette emphasis (Eq. 6), normalized to [0, 1].
+
+    ``silhouette_strength`` is ``1 - |n·view|`` when a normal map is available,
+    otherwise a high-gradient edge proxy in ``[0, 1]``.
+    """
+    raw = tone * (ksc + kss * np.power(silhouette_strength, kse))
+    return _normalize01(raw)
+
+
+def interior_factor(grad_mag, kte):
+    """Lu et al. interior/sparsity factor (Eq. 9), normalized to [0, 1]."""
+    return _normalize01(np.power(np.clip(grad_mag, 0.0, 1.0), kte))
+
+
+def lighting_factor(normals, light, kle):
+    """Shading modulation from surface normals, normalized to [0, 1]."""
+    ndotl = np.sum(normals * light, axis=-1)
+    raw = np.power(np.clip(1.0 - ndotl, 0.0, 1.0), kle)
+    return _normalize01(raw)
+
+
+def depth_factor(depth01, kde):
+    """Depth attenuation: far regions sparser (simplified from Eq. 8)."""
+    raw = np.power(np.clip(1.0 - depth01, 0.0, 1.0), max(kde, 1e-3))
+    return _normalize01(raw)
+
+
+def build_illustration_density(
+    tone,
+    params,
+    grad_mag=None,
+    gx=None,
+    gy=None,
+    normals=None,
+    normals_from_map=False,
+    depth01=None,
+):
+    """
+    Combine tone with optional illustration factors into one density field.
+    """
+    if not params.active:
+        return tone
+
+    if grad_mag is None or gx is None or gy is None:
+        gx, gy, grad_mag = compute_image_gradient(tone, params.gradient_sigma)
+    if normals is None and (
+        params.silhouette_density
+        or params.lighting
+        or params.silhouette_curves
+    ):
+        normals = normals_from_gradient(gx, gy)
+
+    density = tone.copy()
+    if params.boundary:
+        density *= boundary_factor(
+            tone,
+            grad_mag,
+            params.boundary_kgc,
+            params.boundary_kgs,
+            params.boundary_kge
+        )
+    if params.silhouette_density:
+        if normals_from_map:
+            sil = (
+                1.0 - np.clip(
+                    np.abs(np.sum(normals * params.view, axis=-1)),
+                    0.0,
+                    1.0
+                )
+            )
+        else:
+            sil = grad_mag
+        density *= silhouette_factor(
+            tone,
+            sil,
+            params.silhouette_ksc,
+            params.silhouette_kss,
+            params.silhouette_kse
+        )
+    if params.interior:
+        density *= interior_factor(grad_mag, params.interior_kte)
+    if params.lighting:
+        density *= lighting_factor(normals, params.light, params.lighting_kle)
+    if params.depth and depth01 is not None:
+        density *= depth_factor(depth01, params.depth_kde)
+
+    return np.clip(density, 0.0, 1.0)
+
+
+def gradient_size_scale(grad_mag, strength):
+    """Per-pixel radius multiplier from gradient magnitude."""
+    if strength <= 0:
+        return None
+    return 1.0 + strength * grad_mag
+
+
+def extract_silhouette_curves(tone, gx, gy, grad_mag, params, normals=None,
+                              normals_from_map=False):
+    """Return line segments ``[((x0,y0),(x1,y1)), ...]`` in y-up coords."""
+    if not params.silhouette_curves:
+        return []
+
+    log = compute_log(tone, params.gradient_sigma)
+
+    grad_dot_view = gx * params.view[0] + gy * params.view[1]
+    if np.linalg.norm(params.view[:2]) < 1e-6:
+        grad_dot_view = gy
+
+    mask = (
+        (tone * log < params.curve_threshold_log)
+        & (grad_dot_view < params.curve_threshold_eye)
+        & (grad_mag > params.curve_threshold_grad)
+    )
+    if normals_from_map and normals is not None:
+        ndv = np.abs(np.sum(normals * params.view, axis=-1))
+        mask &= ndv < params.curve_threshold_eye
+
+    dir_x = gy
+    dir_y = -gx
+    length = np.hypot(dir_x, dir_y)
+    length = np.maximum(length, 1e-8)
+    dir_x = dir_x / length
+    dir_y = dir_y / length
+
+    ys, xs = np.where(mask)
+    if params.curve_stride > 1:
+        keep = (
+            (xs % params.curve_stride == 0) &
+            (ys % params.curve_stride == 0)
+        )
+        xs = xs[keep]
+        ys = ys[keep]
+
+    half = params.curve_length * 0.5
+    segments = []
+    for x, y in zip(xs, ys):
+        dx = dir_x[y, x] * half
+        dy = dir_y[y, x] * half
+        segments.append(((x - dx, y - dy), (x + dx, y + dy)))
+    return segments