ryan/hypertower
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

began work on v3

Browse Source
This commit is contained in:
rpotter6298
2026-03-19 16:58:29 +01:00
parent 786457b30d
commit eb9eafe715
42 changed files with 11214 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
portable_versions/image_loader.py
+351
View File
@@ -0,0 +1,351 @@
"""
portable_versions/image_loader.py
==================================
A self-contained image loader with in-memory caching, an optional
preprocessing pipeline (e.g. disc cropping), and composable augmentations.
Returns plain NumPy arrays — works with PyTorch, TensorFlow, JAX, or
anything else that can consume an ndarray.
Dependencies: Pillow, numpy (nothing else)
Quickstart
----------
from portable_versions.image_loader import ImageLoader, RandomHorizontalFlip, RandomRotation, ColorJitter
# 1. Build the loader (once per run)
loader = ImageLoader(
target_size=(200, 200),
normalize=True, # float32 in [0, 1] with ImageNet mean/std
cache=True, # each image decoded from disk only once
workers=4, # parallel cache warm-up threads
preprocessor=my_crop_fn, # optional callable(PIL.Image) -> PIL.Image
)
# 2. Attach augmentations (applied randomly and independently per call)
loader.augmentation = [
RandomHorizontalFlip(p=0.5),
RandomRotation(degrees=15),
ColorJitter(brightness=0.2, contrast=0.2, saturation=0.1, hue=0.05),
]
# 3. Warm the cache up front (optional but fast)
loader.warm(all_paths)
# 4. Fetch images by path list — call as many times as you like
# Returns ndarray of shape (N, H, W, 3), dtype float32
imgs = loader.get_img(train_paths)
# For TensorFlow:
import tensorflow as tf
tensor = tf.constant(imgs) # (N, H, W, 3)
# For PyTorch:
import torch
tensor = torch.from_numpy(imgs).permute(0, 3, 1, 2) # (N, C, H, W)
Augmentations reference
-----------------------
All augmentation classes live in this file and depend only on PIL + numpy.
RandomHorizontalFlip(p=0.5)
RandomVerticalFlip(p=0.5)
RandomRotation(degrees=15)
ColorJitter(brightness=0.2, contrast=0.2, saturation=0.1, hue=0.05)
RandomGrayscale(p=0.1)
You can also pass any callable(PIL.Image.Image) -> PIL.Image.Image as an
augmentation step.
"""
from __future__ import annotations
import random
import threading
from concurrent.futures import ThreadPoolExecutor, as_completed
from pathlib import Path
from typing import Callable, Iterable, List, Optional, Tuple, Union
import numpy as np
from PIL import Image, ImageEnhance, ImageOps
# ImageNet channel statistics (RGB)
_IMAGENET_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
_IMAGENET_STD = np.array([0.229, 0.224, 0.225], dtype=np.float32)
PathLike = Union[str, Path]
def _call_preprocessor(
fn: Callable[..., Image.Image],
img: Image.Image,
path: Path,
) -> Image.Image:
"""Call preprocessor as fn(img, path) if it accepts two args, else fn(img)."""
try:
return fn(img, path)
except TypeError:
return fn(img)
# ---------------------------------------------------------------------------
# Core loader
# ---------------------------------------------------------------------------
class ImageLoader:
"""
Preprocessing pipeline + in-memory cache + augmentation, returning NumPy.
Parameters
----------
target_size : (height, width)
Output spatial dimensions. Applied after ``preprocessor`` (if any).
Ignored when a ``preprocessor`` already resizes to the right size.
normalize : bool
When True, output is float32 with ImageNet mean/std subtraction.
When False, output is uint8 in [0, 255].
cache : bool
Store decoded+preprocessed images in RAM so each file is read from
disk at most once. The cache persists across ``get_img`` calls.
workers : int
Thread count for ``warm()``. 0 or 1 = single-threaded.
preprocessor : callable, optional
Called as ``preprocessor(img: PIL.Image) -> PIL.Image`` before
resizing and caching. Use this for disc cropping, padding, etc.
augmentation : list of callables
Each element is called as ``fn(img: PIL.Image) -> PIL.Image``.
Applied **after** cache retrieval, so augmentations are NOT cached —
they are re-sampled independently on every ``get_img`` call.
"""
def __init__(
self,
target_size: Tuple[int, int] = (224, 224),
*,
normalize: bool = True,
cache: bool = True,
workers: int = 4,
preprocessor: Optional[Callable[[Image.Image], Image.Image]] = None,
) -> None:
self.target_size = target_size
self.normalize = normalize
self.workers = workers
self.preprocessor = preprocessor
self.augmentation: List[Callable[[Image.Image], Image.Image]] = []
self._cache: Optional[dict[str, np.ndarray]] = {} if cache else None
self._lock = threading.Lock()
# ------------------------------------------------------------------
# Public
# ------------------------------------------------------------------
def warm(self, paths: Iterable[PathLike]) -> None:
"""
Pre-load all *paths* into the cache in parallel.
Already-cached paths are skipped, so calling ``warm`` multiple
times (e.g. once per fold) is safe and only loads new images.
"""
if self._cache is None:
return
paths = [str(p) for p in paths]
to_warm = [p for p in paths if p not in self._cache]
if not to_warm:
return
already = len(paths) - len(to_warm)
print(
f"[ImageLoader] warming {len(to_warm)} images"
+ (f" ({already} already cached)" if already else ""),
flush=True,
)
def _load_one(path_str: str) -> None:
arr = self._decode(path_str)
with self._lock:
self._cache.setdefault(path_str, arr)
if self.workers <= 1:
for p in to_warm:
_load_one(p)
else:
with ThreadPoolExecutor(max_workers=self.workers) as ex:
futures = {ex.submit(_load_one, p): p for p in to_warm}
for fut in as_completed(futures):
fut.result()
def get_img(
self,
paths: Iterable[PathLike],
augment: bool = True,
) -> np.ndarray:
"""
Return images for the given paths as a single NumPy array.
Parameters
----------
paths : iterable of path-like
File paths to load. If the cache is enabled and a path has
been warmed (or loaded before), it is served from RAM.
augment : bool
Apply ``self.augmentation`` pipeline. Set to False at eval time.
Returns
-------
np.ndarray, shape (N, H, W, 3)
float32 in [0, 1] (or normalised) if ``self.normalize`` is True,
otherwise uint8 in [0, 255].
"""
imgs = []
for p in paths:
img = self._get_one(str(p), augment=augment)
imgs.append(img)
return np.stack(imgs, axis=0)
# ------------------------------------------------------------------
# Internal
# ------------------------------------------------------------------
def _decode(self, path_str: str) -> np.ndarray:
"""Open, preprocess, and resize → uint8 HWC ndarray (for the cache)."""
img = Image.open(path_str).convert("RGB")
if self.preprocessor is not None:
img = _call_preprocessor(self.preprocessor, img, Path(path_str))
# Only resize here if preprocessor didn't already produce target_size
if img.size != (self.target_size[1], self.target_size[0]):
img = img.resize((self.target_size[1], self.target_size[0]), Image.BILINEAR)
return np.asarray(img, dtype=np.uint8)
def _get_one(self, path_str: str, augment: bool) -> np.ndarray:
if self._cache is not None:
arr = self._cache.get(path_str)
if arr is None:
arr = self._decode(path_str)
with self._lock:
self._cache.setdefault(path_str, arr)
img = Image.fromarray(arr, mode="RGB")
else:
img = Image.open(path_str).convert("RGB")
if self.preprocessor is not None:
img = self.preprocessor(img)
if img.size != (self.target_size[1], self.target_size[0]):
img = img.resize((self.target_size[1], self.target_size[0]), Image.BILINEAR)
if augment and self.augmentation:
for fn in self.augmentation:
img = fn(img)
arr = np.asarray(img, dtype=np.float32) / 255.0
if self.normalize:
arr = (arr - _IMAGENET_MEAN) / _IMAGENET_STD
else:
arr = (arr * 255).clip(0, 255).astype(np.uint8)
return arr
def __len__(self) -> int:
"""Number of images currently in the cache."""
return len(self._cache) if self._cache is not None else 0
def __repr__(self) -> str:
return (
f"ImageLoader(target_size={self.target_size}, "
f"normalize={self.normalize}, "
f"cached={len(self)}, "
f"augmentations={len(self.augmentation)})"
)
# ---------------------------------------------------------------------------
# Augmentation primitives (PIL-only, no torch/tf dependencies)
# ---------------------------------------------------------------------------
class RandomHorizontalFlip:
"""Flip image left-right with probability *p*."""
def __init__(self, p: float = 0.5):
self.p = p
def __call__(self, img: Image.Image) -> Image.Image:
return ImageOps.mirror(img) if random.random() < self.p else img
class RandomVerticalFlip:
"""Flip image top-bottom with probability *p*."""
def __init__(self, p: float = 0.5):
self.p = p
def __call__(self, img: Image.Image) -> Image.Image:
return ImageOps.flip(img) if random.random() < self.p else img
class RandomRotation:
"""Rotate by a uniformly-sampled angle in [-degrees, +degrees]."""
def __init__(self, degrees: float = 15):
self.degrees = degrees
def __call__(self, img: Image.Image) -> Image.Image:
angle = random.uniform(-self.degrees, self.degrees)
return img.rotate(angle, resample=Image.BILINEAR, expand=False)
class ColorJitter:
"""
Randomly jitter brightness, contrast, saturation, and hue.
Each factor is sampled uniformly from [1 - amount, 1 + amount].
Hue shift is sampled from [-hue, +hue] (range 0–0.5).
Pass 0 for any channel to leave it unchanged.
"""
def __init__(
self,
brightness: float = 0.2,
contrast: float = 0.2,
saturation: float = 0.1,
hue: float = 0.05,
):
self.brightness = brightness
self.contrast = contrast
self.saturation = saturation
self.hue = hue
def __call__(self, img: Image.Image) -> Image.Image:
ops = []
if self.brightness:
ops.append(("brightness", self.brightness))
if self.contrast:
ops.append(("contrast", self.contrast))
if self.saturation:
ops.append(("saturation", self.saturation))
if self.hue:
ops.append(("hue", self.hue))
random.shuffle(ops)
for kind, amount in ops:
factor = random.uniform(1 - amount, 1 + amount)
if kind == "brightness":
img = ImageEnhance.Brightness(img).enhance(factor)
elif kind == "contrast":
img = ImageEnhance.Contrast(img).enhance(factor)
elif kind == "saturation":
img = ImageEnhance.Color(img).enhance(factor)
elif kind == "hue":
# PIL has no direct hue enhancer — shift via HSV in numpy
arr = np.asarray(img.convert("HSV"), dtype=np.int16)
shift = int(random.uniform(-self.hue, self.hue) * 255)
arr[:, :, 0] = (arr[:, :, 0] + shift) % 256
img = Image.fromarray(arr.astype(np.uint8), mode="HSV").convert("RGB")
return img
class RandomGrayscale:
"""Convert to grayscale (keeping 3 channels) with probability *p*."""
def __init__(self, p: float = 0.1):
self.p = p
def __call__(self, img: Image.Image) -> Image.Image:
if random.random() < self.p:
img = ImageOps.grayscale(img).convert("RGB")
return img
portable_versions/refuge_mask_adapter.py
+270
View File
@@ -0,0 +1,270 @@
"""
portable_versions/refuge_mask_adapter.py
=========================================
Optic-disc cropper for REFUGE (and REFUGE2) fundus images, designed as a
drop-in ``preprocessor`` for ``ImageLoader``.
Given an image and its corresponding segmentation mask, it:
1. Extracts the optic disc region from the mask
2. Computes a padded bounding box around it
3. Crops and resizes the original image
Dependencies: Pillow, numpy (nothing else)
Quickstart
----------
from portable_versions.image_loader import ImageLoader, RandomHorizontalFlip, RandomRotation, ColorJitter
from portable_versions.refuge_mask_adapter import RefugeMaskCropper
cropper = RefugeMaskCropper(
mask_dir="REFUGE/Annotations/Training400/Disc_Cup_Masks",
scale=1.5, # context around disc (1.0 = tight, 2.0 = lots of context)
target_size=(200, 200), # output size — should match ImageLoader target_size
mask_suffix=".bmp", # REFUGE1 uses .bmp; REFUGE2 uses .png
)
loader = ImageLoader(
target_size=(200, 200),
normalize=True,
preprocessor=cropper,
)
loader.augmentation = [
RandomHorizontalFlip(),
RandomRotation(15),
ColorJitter(0.2, 0.2, 0.1, 0.05),
]
imgs = loader.get_img(image_paths, augment=True) # (N, 200, 200, 3)
REFUGE mask formats
-------------------
REFUGE1 Grayscale BMP: background=128, disc=255, cup=0
REFUGE2 RGB PNG: background detected from image borders, disc/cup by colour
Both are handled automatically.
Directory structure assumption
------------------------------
The cropper looks for the mask with the same stem as the image file, inside
``mask_dir``. If your layout differs, pass a custom ``mask_path_fn``:
cropper = RefugeMaskCropper(
mask_path_fn=lambda img_path: img_path.with_suffix(".bmp"),
scale=1.5,
target_size=(200, 200),
)
"""
from __future__ import annotations
from collections import Counter
from pathlib import Path
from typing import Optional, Tuple
import numpy as np
from PIL import Image
_MASK_DIR_NAMES = {"Disc_Cup_Masks", "Disc_Masks", "Disc_Mask"}
_MASK_SUFFIXES = {".bmp", ".png"}
class RefugeMaskCropper:
"""
Crop a fundus image to the optic disc region using its segmentation mask.
Pass the REFUGE root directory and the cropper will automatically index
all masks underneath it — no need to specify which subdirectory or
file extension.
cropper = RefugeMaskCropper("REFUGE/", scale=1.5)
loader = ImageLoader(target_size=(200, 200), preprocessor=cropper)
imgs = loader.get_img(test_set) # test_set = any list of image paths
Parameters
----------
refuge_root : str or Path
Top-level REFUGE directory. All mask files under directories named
``Disc_Cup_Masks``, ``Disc_Masks``, or ``Disc_Mask`` are indexed
automatically (supports both .bmp and .png).
scale : float
Padding multiplier applied to the disc radius.
1.0 = tight crop, 1.5 = moderate context, 2.5 = lots of context.
target_size : (height, width)
Output size after cropping. Should match ``ImageLoader.target_size``.
"""
def __init__(
self,
refuge_root: str | Path,
*,
scale: float = 1.5,
target_size: Tuple[int, int] = (200, 200),
) -> None:
self.refuge_root = Path(refuge_root)
self.scale = scale
self.target_size = target_size
self._index: dict[str, list[Path]] = {}
self._build_index()
def _build_index(self) -> None:
"""Walk refuge_root and index all mask files by stem (stem → [paths])."""
for mask_dir in self.refuge_root.rglob("*"):
if mask_dir.is_dir() and mask_dir.name in _MASK_DIR_NAMES:
for f in mask_dir.rglob("*"):
if f.is_file() and f.suffix.lower() in _MASK_SUFFIXES:
self._index.setdefault(f.stem, []).append(f)
if not self._index:
raise FileNotFoundError(
f"No mask files found under {self.refuge_root!r}. "
f"Expected directories named: {_MASK_DIR_NAMES}"
)
n_masks = sum(len(v) for v in self._index.values())
print(f"[RefugeMaskCropper] indexed {n_masks} masks ({len(self._index)} unique stems)", flush=True)
# ------------------------------------------------------------------
# Callable interface — drop-in preprocessor for ImageLoader
# ------------------------------------------------------------------
def __call__(
self,
img: Image.Image,
img_path: Optional[str | Path] = None,
) -> Image.Image:
stem = Path(img_path).stem if img_path else None
mask_path = self._lookup(stem, img_path)
disc_mask = _load_disc_mask(mask_path, img.size)
box = _mask_to_crop_box(disc_mask, scale=self.scale, img_size=img.size)
cropped = img.crop(box)
return cropped.resize(
(self.target_size[1], self.target_size[0]), Image.Resampling.BILINEAR
)
def _lookup(self, stem: Optional[str], img_path: Optional[str | Path] = None) -> Path:
if stem is None:
raise ValueError("img_path is required to match the mask.")
candidates = self._index.get(stem)
if not candidates:
raise KeyError(
f"No mask found for image stem {stem!r}. "
f"Available stems (sample): {list(self._index)[:5]}"
)
if len(candidates) == 1:
return candidates[0]
# Pick the mask whose directory components best overlap with img_path
# (ignores the filename itself to handle extension differences)
img_parts = set(Path(img_path).parent.parts) if img_path else set()
return max(candidates, key=lambda m: len(set(m.parent.parts) & img_parts))
def __repr__(self) -> str:
return (
f"RefugeMaskCropper(refuge_root={str(self.refuge_root)!r}, "
f"scale={self.scale}, target_size={self.target_size}, "
f"masks_indexed={len(self._index)})"
)
# ---------------------------------------------------------------------------
# Mask parsing
# ---------------------------------------------------------------------------
def _load_disc_mask(mask_path: Path, img_size: Tuple[int, int]) -> np.ndarray:
"""
Return a binary disc mask (uint8, 1=disc) from a REFUGE mask file.
Handles:
- Grayscale BMP (REFUGE1): background≈128, disc=255, cup=0
- RGB PNG (REFUGE2): background detected from image borders
"""
mask_img = Image.open(mask_path)
if mask_img.mode == "L" or mask_img.mode == "P":
arr = np.asarray(mask_img.convert("L"), dtype=np.uint8)
bg = _border_mode(arr)
disc_mask = (arr != bg).astype(np.uint8)
else:
arr = np.asarray(mask_img.convert("RGB"), dtype=np.uint8)
bg = _border_mode_rgb(arr)
# disc = any non-background pixel
bg_mask = np.all(arr == bg, axis=2)
disc_mask = (~bg_mask).astype(np.uint8)
# Ensure mask matches image spatial size
mh, mw = disc_mask.shape
iw, ih = img_size
if (mw, mh) != (iw, ih):
disc_img = Image.fromarray(disc_mask * 255).resize((iw, ih), Image.NEAREST)
disc_mask = (np.asarray(disc_img) > 0).astype(np.uint8)
return disc_mask
def _border_mode(arr: np.ndarray, border: int = 5) -> int:
"""Most common pixel value along the image border (grayscale)."""
h, w = arr.shape
border_pixels = np.concatenate([
arr[:border, :].ravel(),
arr[-border:, :].ravel(),
arr[:, :border].ravel(),
arr[:, -border:].ravel(),
])
return int(Counter(border_pixels.tolist()).most_common(1)[0][0])
def _border_mode_rgb(arr: np.ndarray, border: int = 5) -> np.ndarray:
"""Most common RGB colour along the image border."""
h, w, _ = arr.shape
border_pixels = np.concatenate([
arr[:border, :].reshape(-1, 3),
arr[-border:, :].reshape(-1, 3),
arr[:, :border].reshape(-1, 3),
arr[:, -border:].reshape(-1, 3),
], axis=0)
tuples = [tuple(row) for row in border_pixels.tolist()]
most_common = Counter(tuples).most_common(1)[0][0]
return np.array(most_common, dtype=np.uint8)
# ---------------------------------------------------------------------------
# Bounding box from mask
# ---------------------------------------------------------------------------
def _mask_to_crop_box(
disc_mask: np.ndarray,
scale: float,
img_size: Tuple[int, int],
) -> Tuple[int, int, int, int]:
"""
Compute a square crop box centred on the disc with padding = scale * radius.
Returns (left, upper, right, lower) — ready for PIL Image.crop().
Falls back to the full image if no disc pixels are found.
"""
coords = np.argwhere(disc_mask > 0) # (N, 2) in (row, col) order
if coords.size == 0:
w, h = img_size
return (0, 0, w, h)
ys, xs = coords[:, 0], coords[:, 1]
centre_x = float(xs.mean())
centre_y = float(ys.mean())
radius = max(float(xs.max() - xs.min()), float(ys.max() - ys.min())) / 2.0
crop_radius = radius * scale
iw, ih = img_size
left = int(max(0, centre_x - crop_radius))
upper = int(max(0, centre_y - crop_radius))
right = int(min(iw, centre_x + crop_radius))
lower = int(min(ih, centre_y + crop_radius))
# Make square by expanding the shorter side
cw, ch = right - left, lower - upper
if cw < ch:
diff = ch - cw
left = max(0, left - diff // 2)
right = min(iw, right + diff // 2)
elif ch < cw:
diff = cw - ch
upper = max(0, upper - diff // 2)
lower = min(ih, lower + diff // 2)
return (left, upper, right, lower)