[refactor] SubImage → SubImageExtract, add SubImageCombine

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/image/sub_image.py

@@ -1,3 +1,4 @@
+import numpy as _np
 from rbm.matrix import Mat, np
 
 def normalize(image: Mat):
@@ -6,7 +7,7 @@ def normalize(image: Mat):
 	std  = np.where(std < 1e-8, np.ones_like(std), std)
 	return (image - mean) / std
 
-class SubImage:
+class SubImageExtract:
 	def __init__(self, sx: int, sy: int, px: int, py: int):
 		self.sx = sx
 		self.sy = sy
@@ -48,6 +49,34 @@ class SubImage:
 
 		return result
 
+class SubImageCombine:
+	def __init__(self, sx: int, sy: int, px: int, py: int, image_h: int, image_w: int, n_ch: int = 3):
+		self.sx = sx
+		self.sy = sy
+		self.px = px
+		self.py = py
+		self.image_h = image_h
+		self.image_w = image_w
+		self.n_ch = n_ch
+
+	def __call__(self, subimages: Mat) -> _np.ndarray:
+		nx = (self.image_h - self.sx) // self.px + 1
+		ny = (self.image_w - self.sy) // self.py + 1
+
+		accum = _np.zeros((self.n_ch, self.image_h, self.image_w), dtype=_np.float64)
+		count = _np.zeros((1,       self.image_h, self.image_w), dtype=_np.float64)
+
+		for ix in range(nx):
+			for iy in range(ny):
+				patch = _np.asarray(np.reshape(subimages[ix * ny + iy], (self.n_ch, self.sx, self.sy)))
+				x0, y0 = ix * self.px, iy * self.py
+				accum[:, x0:x0+self.sx, y0:y0+self.sy] += patch
+				count[0, x0:x0+self.sx, y0:y0+self.sy] += 1.0
+
+		result = (accum / _np.maximum(count, 1)).transpose(1, 2, 0)
+		lo, hi = result.min(), result.max()
+		return _np.clip((result - lo) / (hi - lo + 1e-8), 0, 1)
+
 def conv2d(image: Mat, kernel: Mat, stride: tuple[int,int]):
 	pad_x = int((kernel.shape[0] - 1)/2)
 	pad_y = int((kernel.shape[1] - 1)/2)

src/tests/test_faces_sub_image.py

@@ -5,7 +5,7 @@ import matplotlib.pyplot as plt
 
 from rbm.model import Model
 from rbm.entity import Entity, EntityParams, TrainingParams
-from image.sub_image import SubImage, normalize
+from image.sub_image import SubImageExtract, normalize
 from rbm.matrix import Mat, np, convert
 from rbm.status import CheckpointStatus
 
@@ -38,7 +38,7 @@ class TestModel(Model):
 
 
 def pad_to_stride(img: numpy.ndarray) -> numpy.ndarray:
-	"""Pad so (H - PATCH) and (W - PATCH) are divisible by STRIDE (required by SubImage.check)."""
+	"""Pad so (H - PATCH) and (W - PATCH) are divisible by STRIDE (required by SubImageExtract.check)."""
 	h, w = img.shape[:2]
 	ph = (-h) % STRIDE if h >= PATCH else PATCH - h
 	pw = (-w) % STRIDE if w >= PATCH else PATCH - w
@@ -86,8 +86,8 @@ def load_patches(data_dir: str, n_images: int = N_IMAGES, start: int = 0):
 
 
 def load_image_patches(path: str):
-	"""Extract normalised patches from a single image via SubImage; return (patches, nx_steps, ny_steps)."""
-	sub = SubImage(PATCH, PATCH, STRIDE, STRIDE)
+	"""Extract normalised patches from a single image via SubImageExtract; return (patches, nx_steps, ny_steps)."""
+	sub = SubImageExtract(PATCH, PATCH, STRIDE, STRIDE)
 	img = cv2.imread(path)
 	img = pad_to_stride(img)
 	h, w = img.shape[:2]

src/tests/test_sub_image.py

@@ -1,4 +1,4 @@
-from image.sub_image import SubImage
+from image.sub_image import SubImageExtract
 from rbm.matrix import np
 
 
@@ -8,7 +8,7 @@ if __name__ == "__main__":
 	w = 8
 	h = 8
 	img_rbb = np.reshape(np.linspace(1, n*c*w*h, num=n*c*w*h, dtype=np.float64), (n, c, w, h))
-	sub = SubImage(4, 4, 1, 1)
+	sub = SubImageExtract(4, 4, 1, 1)
 	sub(img_rbb, 3)
 
 	img_gray = np.reshape(np.linspace(1, n*w*h, num=n*w*h, dtype=np.float64), (n, w, h))