dynamo-figures 0.3.2__py3-none-any.whl

dynamo_figures/__init__.py

@@ -0,0 +1,13 @@
+"""
+dynamo_figures - A Python package for dynamic figure generation
+"""
+
+__version__ = "0.3.2"
+
+from dynamo_figures.composite_image import CompositeImage, CompositeMode
+from dynamo_figures.video_to_gif import VideoToGif
+from dynamo_figures.qr_code import QRCode
+from dynamo_figures.blur_faces import FaceBlur
+from dynamo_figures.tex2img import TexToImage
+
+__all__ = ["CompositeImage", "CompositeMode", "VideoToGif", "QRCode", "FaceBlur", "TexToImage", "__version__"]

dynamo_figures/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running composite_image as a module."""
+
+from dynamo_figures.composite_image import main
+
+if __name__ == "__main__":
+    main()

dynamo_figures/blur_faces/__init__.py

@@ -0,0 +1,18 @@
+"""
+    Package: dynamo_figures.blur_faces
+    Description: Anonymize faces in photos and videos, fully locally.
+
+    Modules:
+        core       FaceBlur, the high-level image/video API
+        detectors  YuNet detection on CPU (OpenCV) or GPU (ONNX Runtime)
+        tracking   Frame-to-frame box smoothing and hold for videos
+        obscure    Blur / pixelate / fill rendering
+        video_io   Threaded frame reading and ffmpeg encoding
+        cli        The dynamo-blur-faces command-line tool
+"""
+
+from dynamo_figures.blur_faces.core import FaceBlur
+from dynamo_figures.blur_faces.detectors import gpu_provider
+from dynamo_figures.blur_faces.tracking import FaceTracker
+
+__all__ = ["FaceBlur", "FaceTracker", "gpu_provider"]

dynamo_figures/blur_faces/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running blur_faces as a module: python -m dynamo_figures.blur_faces"""
+
+from dynamo_figures.blur_faces.cli import main
+
+if __name__ == "__main__":
+    main()

dynamo_figures/blur_faces/cli.py

@@ -0,0 +1,150 @@
+"""
+    File: cli.py
+    Description: Command-line interface for the dynamo-blur-faces tool.
+    Blurs, pixelates, or covers faces in a photo or video, fully locally.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from dynamo_figures.blur_faces.core import FaceBlur
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.tif', '.tiff', '.webp'}
+VIDEO_EXTENSIONS = {'.mp4', '.mov', '.avi', '.mkv', '.m4v', '.webm', '.wmv'}
+
+
+def main():
+    """Main function for command-line interface."""
+    parser = argparse.ArgumentParser(
+        prog='dynamo-blur-faces',
+        description='Blur, pixelate, or cover faces in a photo or video. Runs fully locally.',
+        epilog='-'
+    )
+    parser.add_argument('--input', type=str, required=True,
+                        help='path of input image or video file.')
+    parser.add_argument('--output', type=str, default=None,
+                        help='output file path (default: same directory as input with _blurred suffix)')
+    parser.add_argument('--style', default='blur', choices=FaceBlur.STYLES,
+                        help='how to obscure faces (default: blur)')
+    parser.add_argument('--shape', default='ellipse', choices=FaceBlur.SHAPES,
+                        help='shape of the obscured region (default: ellipse)')
+    parser.add_argument('--padding', type=float, default=0.25,
+                        help='fraction to enlarge each face box on every side (default: 0.25)')
+    parser.add_argument('--blur_strength', type=float, default=0.5,
+                        help='blur kernel size as a fraction of face size, for --style blur (default: 0.5)')
+    parser.add_argument('--pixel_blocks', type=int, default=10,
+                        help='number of mosaic blocks across each face, for --style pixelate (default: 10)')
+    parser.add_argument('--fill_color', type=str, default='black',
+                        help='color name or hex code, for --style fill (default: black)')
+    parser.add_argument('--score_threshold', type=float, default=0.6,
+                        help='minimum detection confidence 0..1; lower catches more faces but more false positives (default: 0.6)')
+    parser.add_argument('--nms_threshold', type=float, default=0.3,
+                        help='overlap threshold for merging duplicate detections (default: 0.3)')
+    parser.add_argument('--detect_max_dim', type=int, default=2048,
+                        help='downscale so the longest side is at most this before detection; '
+                             'raise for tiny faces, lower for speed, 0 = full resolution (default: 2048)')
+    parser.add_argument('--device', default='auto', choices=FaceBlur.DEVICES,
+                        help='detection device: gpu needs onnxruntime (CoreML) or onnxruntime-gpu (CUDA); '
+                             'auto uses the GPU when available (default: auto)')
+    parser.add_argument('--batch_size', type=int, default=8,
+                        help='video only: frames detected per batch (default: 8)')
+    parser.add_argument('--workers', type=int, default=None,
+                        help='video only: CPU threads for detection/blurring (default: number of cores)')
+    parser.add_argument('--hold_frames', type=int, default=5,
+                        help='video only: keep obscuring a face for this many frames after it is lost (default: 5)')
+    parser.add_argument('--smoothing', type=float, default=0.5,
+                        help='video only: box smoothing between frames, 0..1 (0 = off; higher is steadier '
+                             'but lags; the raw detection is always covered) (default: 0.5)')
+    parser.add_argument('--start_t', type=float, default=None,
+                        help='video only: trim the output to start this many seconds into the input '
+                             '(default: start of video)')
+    parser.add_argument('--end_t', type=float, default=None,
+                        help='video only: trim the output to end this many seconds into the input '
+                             '(default: end of video)')
+    parser.add_argument('--no_audio', action='store_true',
+                        help='video only: drop the audio track')
+    parser.add_argument('--crf', type=int, default=18,
+                        help='video only: H.264 quality, lower is better (default: 18)')
+    parser.add_argument('--draw_boxes', action='store_true',
+                        help='draw detection boxes and scores instead of obscuring (for tuning)')
+    parser.add_argument('--disable_pbar', action='store_true',
+                        help='disable progress bar when processing videos')
+
+    args = parser.parse_args()
+
+    input_path = Path(args.input)
+    if not input_path.exists():
+        print(f"Error: Input file '{input_path}' not found.")
+        sys.exit(1)
+
+    ext = input_path.suffix.lower()
+    if ext in IMAGE_EXTENSIONS:
+        is_video = False
+    elif ext in VIDEO_EXTENSIONS:
+        is_video = True
+    else:
+        print(f"Error: Unsupported file type '{ext}'.")
+        sys.exit(1)
+
+    if args.output:
+        output_path = args.output
+    else:
+        out_ext = '.mp4' if is_video else ext
+        output_path = str(input_path.parent / f'{input_path.stem}_blurred{out_ext}')
+
+    print(" -- Load Param: input", input_path)
+    print(" -- Load Param: output", output_path)
+    print(" -- Load Param: style", args.style)
+    print(" -- Load Param: shape", args.shape)
+    print(" -- Load Param: score_threshold", args.score_threshold)
+    print(" -- Load Param: device", args.device)
+
+    if not 0 <= args.smoothing < 1:
+        print("Error: --smoothing must be in [0, 1).")
+        sys.exit(1)
+
+    if not is_video and (args.start_t is not None or args.end_t is not None):
+        print("Error: --start_t/--end_t only apply to videos.")
+        sys.exit(1)
+
+    if args.start_t is not None and args.start_t < 0:
+        print("Error: --start_t must be >= 0.")
+        sys.exit(1)
+
+    if args.end_t is not None and args.end_t <= (args.start_t or 0.0):
+        print("Error: --end_t must be greater than --start_t.")
+        sys.exit(1)
+
+    blurrer = FaceBlur(
+        style=args.style,
+        shape=args.shape,
+        padding=args.padding,
+        score_threshold=args.score_threshold,
+        nms_threshold=args.nms_threshold,
+        detect_max_dim=args.detect_max_dim,
+        blur_strength=args.blur_strength,
+        pixel_blocks=args.pixel_blocks,
+        fill_color=args.fill_color,
+        hold_frames=args.hold_frames,
+        smoothing=args.smoothing,
+        draw_boxes=args.draw_boxes,
+        disable_pbar=args.disable_pbar,
+        device=args.device,
+        batch_size=args.batch_size,
+        workers=args.workers,
+    )
+
+    if is_video:
+        success = blurrer.process_video(str(input_path), output_path,
+                                        keep_audio=not args.no_audio, crf=args.crf,
+                                        start_t=args.start_t, end_t=args.end_t)
+    else:
+        success = blurrer.process_image(str(input_path), output_path)
+
+    if not success:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

dynamo_figures/blur_faces/core.py

@@ -0,0 +1,277 @@
+"""
+    File: core.py
+    Description: FaceBlur, the high-level API for anonymizing faces in images
+    and videos. Combines a detector (detectors.py), a tracker (tracking.py),
+    an obscurer (obscure.py), and threaded video I/O (video_io.py).
+"""
+
+import os
+import shutil
+import tempfile
+from collections import deque
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+import cv2
+from tqdm import tqdm
+
+from dynamo_figures.blur_faces.detectors import DEVICES, create_detector
+from dynamo_figures.blur_faces.obscure import SHAPES, STYLES, Obscurer
+from dynamo_figures.blur_faces.tracking import FaceTracker
+from dynamo_figures.blur_faces.video_io import FrameReader, open_writer
+
+
+class FaceBlur:
+    """Class for detecting and obscuring faces in images and videos."""
+
+    STYLES = STYLES
+    SHAPES = SHAPES
+    DEVICES = DEVICES
+
+    def __init__(self, style='blur', shape='ellipse', padding=0.25,
+                 score_threshold=0.6, nms_threshold=0.3, detect_max_dim=2048,
+                 blur_strength=0.5, pixel_blocks=10, fill_color='black',
+                 hold_frames=5, smoothing=0.5, draw_boxes=False, disable_pbar=False,
+                 device='auto', batch_size=8, workers=None):
+        """
+        Initialize FaceBlur.
+
+        Args:
+            style: How to obscure faces: 'blur', 'pixelate', or 'fill'
+            shape: Region shape to obscure: 'ellipse' or 'rect'
+            padding: Fraction to enlarge each face box by on every side
+            score_threshold: Minimum detector confidence (0..1)
+            nms_threshold: Non-maximum suppression IoU threshold (0..1)
+            detect_max_dim: Downscale frames so the longest side is at most this
+                            many pixels before detection (0 = full resolution)
+            blur_strength: Blur kernel size as a fraction of face size
+            pixel_blocks: Number of mosaic blocks across each face (pixelate)
+            fill_color: Color name or hex code for the 'fill' style
+            hold_frames: (Video) keep obscuring a face for this many frames
+                         after the detector loses it
+            smoothing: (Video) box smoothing between frames (0..1, 0 = off)
+            draw_boxes: Draw detection boxes and scores instead of obscuring
+            disable_pbar: Disable the progress bar for videos
+            device: 'gpu' (ONNX Runtime with CUDA/CoreML), 'cpu' (OpenCV), or
+                    'auto' (GPU if available, otherwise CPU)
+            batch_size: (Video) number of frames detected per batch
+            workers: (Video) number of CPU threads (default: number of cores)
+        """
+        self.obscurer = Obscurer(style, shape, padding, blur_strength,
+                                 pixel_blocks, fill_color, draw_boxes)
+        self.tracker = FaceTracker(hold_frames, smoothing)
+        self.detector = create_detector(device, score_threshold, nms_threshold)
+        self.detect_max_dim = detect_max_dim
+        self.disable_pbar = disable_pbar
+        self.batch_size = max(1, batch_size)
+        self.workers = workers or os.cpu_count() or 4
+
+    @property
+    def device_name(self):
+        """Human-readable name of the detection backend."""
+        return self.detector.name
+
+    def _downscale(self, image):
+        """Resize an image for detection; returns (image, scale)."""
+        h, w = image.shape[:2]
+        if self.detect_max_dim and max(h, w) > self.detect_max_dim:
+            scale = self.detect_max_dim / max(h, w)
+            small = cv2.resize(image, (round(w * scale), round(h * scale)),
+                               interpolation=cv2.INTER_AREA)
+            return small, scale
+        return image, 1.0
+
+    def detect_batch(self, images):
+        """
+        Detect faces in a list of same-sized images.
+
+        Args:
+            images: list of BGR images (numpy arrays) with identical shapes
+
+        Returns:
+            list: one list of (x, y, w, h, score) tuples per image, in
+                  original image coordinates
+        """
+        scaled = [self._downscale(im) for im in images]
+        scale = scaled[0][1]
+        smalls = [s[0] for s in scaled]
+        if self.detector.batched and 1 < len(smalls) < self.batch_size:
+            # Pad partial batches so the GPU session for this batch size is reused
+            smalls = smalls + [smalls[-1]] * (self.batch_size - len(smalls))
+        detections = self.detector.detect_batch(smalls)[:len(images)]
+        return [[(x / scale, y / scale, w / scale, h / scale, s) for x, y, w, h, s in faces]
+                for faces in detections]
+
+    def detect(self, image):
+        """
+        Detect faces in an image.
+
+        Args:
+            image: BGR image (numpy array)
+
+        Returns:
+            list: (x, y, w, h, score) tuples in original image coordinates
+        """
+        return self.detect_batch([image])[0]
+
+    def apply(self, image, faces, inplace=False):
+        """
+        Obscure (or annotate) the given faces in an image.
+
+        Args:
+            image: BGR image (numpy array)
+            faces: list of (x, y, w, h, score) tuples
+            inplace: modify image directly instead of a copy
+
+        Returns:
+            numpy array: the processed image
+        """
+        return self.obscurer.apply(image, faces, inplace)
+
+    def process_image(self, input_path, output_path):
+        """
+        Obscure faces in an image file and save the result.
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        image = cv2.imread(input_path)
+        if image is None:
+            print(f"Error: Could not read image '{input_path}'.")
+            return False
+
+        print(f" -- Image info: {image.shape[1]}x{image.shape[0]}")
+        faces = self.detect(image)
+        print(f" -- Detected {len(faces)} face(s)")
+        result = self.apply(image, faces, inplace=True)
+
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+        if not cv2.imwrite(output_path, result):
+            print(f"Error: Could not save image to '{output_path}'")
+            return False
+        print(f" -- Output saved to: {output_path}")
+        return True
+
+    def process_video(self, input_path, output_path, keep_audio=True, crf=18,
+                      start_t=None, end_t=None):
+        """
+        Obscure faces in every frame of a video file and save the result.
+
+        Frames are decoded on a background thread, detected in batches,
+        tracked in order, obscured on a thread pool, and streamed to the
+        encoder in their original order.
+
+        Args:
+            input_path: Path to the input video
+            output_path: Path for the output video
+            keep_audio: Copy the original audio track (requires ffmpeg)
+            crf: H.264 quality when encoding with ffmpeg (lower = better)
+            start_t: Trim the output to start at this many seconds in
+                     (None or 0 = from the beginning)
+            end_t: Trim the output to end at this many seconds in, exclusive
+                   (None = to the end of the video)
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        if start_t is not None and start_t < 0:
+            print("Error: start_t must be >= 0.")
+            return False
+        if start_t is not None and end_t is not None and end_t <= start_t:
+            print("Error: end_t must be greater than start_t.")
+            return False
+
+        cap = cv2.VideoCapture(input_path)
+        if not cap.isOpened():
+            print(f"Error: Could not open video file '{input_path}'.")
+            return False
+
+        fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+        total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+        start_frame = round((start_t or 0.0) * fps)
+        if start_frame and not cap.set(cv2.CAP_PROP_POS_FRAMES, start_frame):
+            print(f"Error: Could not seek to {start_t:g}s in '{input_path}'.")
+            cap.release()
+            return False
+
+        ret, first = cap.read()
+        if not ret:
+            where = f' at {start_t:g}s' if start_frame else ''
+            print(f"Error: Could not read frames from '{input_path}'{where}.")
+            cap.release()
+            return False
+
+        max_frames = None
+        if end_t is not None:
+            max_frames = max(1, round(end_t * fps) - start_frame)
+        # Use the decoded frame size, which already accounts for rotation metadata
+        height, width = first.shape[:2]
+        frame_count = max(0, total_frames - start_frame) or total_frames
+        if max_frames is not None and frame_count:
+            frame_count = min(frame_count, max_frames)
+        print(f" -- Video info: {width}x{height}, {total_frames} frames, {fps:.2f} FPS")
+        if start_frame or max_frames is not None:
+            end_label = f'{end_t:g}s' if end_t is not None else 'end'
+            print(f" -- Trimming to {(start_t or 0.0):g}s..{end_label} ({frame_count} frames)")
+        print(f" -- Detector: {self.device_name}, batch size {self.batch_size}, {self.workers} worker(s)")
+
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+        tmp_dir = tempfile.mkdtemp(prefix='blur_faces_')
+        try:
+            writer = open_writer(output_path, width, height, fps, crf,
+                                 audio_source=input_path if keep_audio else None, log_dir=tmp_dir,
+                                 audio_start=start_frame / fps if (start_frame or max_frames is not None) else None)
+        except IOError as e:
+            print(f"Error: {e}")
+            cap.release()
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+            return False
+
+        reader = FrameReader(cap, first, max_queue=self.batch_size * 2,
+                             max_frames=max_frames).start()
+
+        # Many single-threaded workers beat OpenCV's own internal threading here
+        prev_threads = cv2.getNumThreads()
+        cv2.setNumThreads(1)
+        executor = ThreadPoolExecutor(self.workers)
+        self.detector.executor = executor
+
+        self.tracker.reset()
+        total_faces = 0
+        frames_with_faces = 0
+        pending = deque()
+        success = True
+        try:
+            with tqdm(total=frame_count, disable=self.disable_pbar, desc="Processing") as pbar:
+                for batch in reader.batches(self.batch_size):
+                    for frame, detections in zip(batch, self.detect_batch(batch)):
+                        total_faces += len(detections)
+                        frames_with_faces += bool(detections)
+                        # Tracking depends on frame order, so it stays on this thread
+                        faces = self.tracker.update(detections)
+                        pending.append(executor.submit(self.apply, frame, faces, True))
+
+                    # Write finished frames in order, keeping a bounded backlog
+                    while pending and (pending[0].done() or len(pending) > self.workers * 2):
+                        writer.write(pending.popleft().result())
+                        pbar.update(1)
+                while pending:
+                    writer.write(pending.popleft().result())
+                    pbar.update(1)
+        except BrokenPipeError:
+            success = False
+        finally:
+            reader.close()
+            cap.release()
+            executor.shutdown(wait=True)
+            cv2.setNumThreads(prev_threads)
+            self.detector.executor = None
+            success = writer.close() and success
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+        print(f" -- Faces found in {frames_with_faces} frame(s), {total_faces} detection(s) total")
+        if not success:
+            return False
+        print(f" -- Output saved to: {output_path}")
+        return True