dictk

500def astronaut(*, width: int = 512, height: int = 512) -> np.ndarray:
501    """Load a bundled real-world grayscale reference image.
502
503    Same parameters and pixel values as the `dictk astronaut` CLI
504    command, minus the file write — see the `dictk` package docstring for
505    why the API layer stops at the array.
506
507    The source is a NASA portrait of astronaut Eileen Collins, from the
508    NASA Great Images database ("No known copyright restrictions, released
509    into the public domain."). It's bundled as a color image and converted
510    with `rgba_to_gray`; unlike `rosta` and `checkerboard`, it isn't
511    procedurally generated, so `width`/`height` other than the native
512    512x512 resize the source image (via `scipy.ndimage.zoom`) rather than
513    computing a fresh pattern at that size.
514
515    Args:
516        width: Image width in pixels. Must be >= 1.
517        height: Image height in pixels. Must be >= 1.
518
519    Returns:
520        A 2D uint8 array of shape (height, width).
521
522    Raises:
523        ValueError: If width or height is less than 1.
524    """
525    if width < 1:
526        raise ValueError(f"width {width} must be >= 1")
527    if height < 1:
528        raise ValueError(f"height {height} must be >= 1")
529
530    asset_path = importlib.resources.files("dictk") / "data" / "astronaut.png"
531    with importlib.resources.as_file(asset_path) as path:
532        color = read(path=path)
533    gray = rgba_to_gray(color)
534
535    native_height, native_width = gray.shape
536    if (width, height) == (native_width, native_height):
537        return gray
538
539    zoom_factors = (height / native_height, width / native_width)
540    resized = zoom(gray.astype(np.float64), zoom_factors, order=3)
541    return np.clip(resized, 0, 255).astype(np.uint8)

465def checkerboard(
466    *, width: int, height: int, count_x: int = 8, count_y: int = 8
467) -> np.ndarray:
468    """Generate a black-and-white checkerboard test image.
469
470    Same parameters and pixel values as the `dictk checkerboard` CLI
471    command, minus the file write — see the `dictk` package docstring for
472    why the API layer stops at the array. count_x and count_y are named for
473    the rectangles they divide the image into, not "squares": unequal
474    counts (or a width/height ratio that doesn't match count_x/count_y)
475    produce rectangular cells, not square ones.
476
477    Args:
478        width: Image width in pixels.
479        height: Image height in pixels.
480        count_x: Number of rectangles along the width. Must be >= 1.
481        count_y: Number of rectangles along the height. Must be >= 1.
482
483    Returns:
484        A 2D uint8 array of shape (height, width) with values 0 or 255.
485
486    Raises:
487        ValueError: If count_x or count_y is less than 1.
488    """
489    if count_x < 1:
490        raise ValueError(f"count_x {count_x} must be >= 1")
491    if count_y < 1:
492        raise ValueError(f"count_y {count_y} must be >= 1")
493
494    rows = (np.arange(height) * count_y // height) % 2
495    cols = (np.arange(width) * count_x // width) % 2
496    pattern = np.logical_xor(rows[:, None], cols[None, :])
497    return (pattern * 255).astype(np.uint8)

100def rosta(
101    *,
102    width: int = 200,
103    height: int = 200,
104    dot_size: float = 4.0,
105    density: float = 0.32,
106    smoothness: float = 2.0,
107    random_seed: int = 42,
108) -> np.ndarray:
109    """Generate a Rosta speckle pattern as a uint8 grayscale image array.
110
111    Same parameters and pixel values as the `dictk rosta` CLI command, minus
112    the file write — see the `dictk` package docstring for why the API
113    layer stops at the array.
114
115    Args:
116        width: Image width in pixels.
117        height: Image height in pixels.
118        dot_size: Size factor for pattern dots (0.0 to 100.0).
119        density: Density of pattern elements (0.0 to 1.0).
120        smoothness: Smoothness factor for final blur (0.0 to 100.0).
121        random_seed: Seed for reproducible random number generation.
122
123    Returns:
124        A 2D uint8 array of shape (height, width), grayscale in [0, 255].
125
126    Raises:
127        ValueError: If dot_size, density, or smoothness is out of range.
128    """
129    rp = RostaParameters(
130        image_size=ImageSize(width=width, height=height),
131        dot_size=dot_size,
132        density=density,
133        smoothness=smoothness,
134        random_seed=random_seed,
135    )
136    pattern = rosta_pattern(rp)
137    return (pattern * 255).astype(np.uint8)