enczoo 0.1.0__tar.gz

enczoo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael J. Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

enczoo-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.3
+Name: enczoo
+Version: 0.1.0
+Summary: Map images (as `PIL.Images`) to intermediate representations (as `np.ndarray`) from off-the-shelf vision models.
+Author: himjl
+Author-email: himjl <mil@mit.edu>
+License: MIT License
+         
+         Copyright (c) 2026 Michael J. Lee
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Requires-Dist: h5py>=3.15.1
+Requires-Dist: pillow>=12.1.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: torch>=2.9.1
+Requires-Dist: torchvision>=0.24.1
+Requires-Dist: tqdm>=4.67.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# `enczoo`: a zoo of encoding models for images
+
+[![CI](https://github.com/himjl/enczoo/actions/workflows/ci.yml/badge.svg)](https://github.com/himjl/enczoo/actions/workflows/ci.yml)
+
+`enczoo` is a Python library with a single goal: to map images (as `PIL.Images`) to intermediate representations (as `np.ndarray`) from off-the-shelf vision models, such as AlexNet and ResNet50.
+
+This library is meant for those who just need to compute off-the-shelf image features once for their project (and perhaps cache them elsewhere).
+
+### Installation
+
+`enczoo` requires Python 3.12 or above, and may be installed using [uv](https://docs.astral.sh/uv/) with the following command: 
+
+>`uv add enczoo`
+ 
+### Usage 
+
+```python
+import enczoo
+import PIL.Image
+image = PIL.Image.open('my-image.png')
+
+model = enczoo.ResNet50(layer_name='avgpool') # try layer4, layer3, ...
+features = model.compute_features(images=[image]) # np.ndarray
+
+# Want another layer? Check out: print(enczoo.ResNet50.layer_names)
+```
+
+### Things `enczoo` handles
+`enczoo` aims to "just work" by solving several tiny problems which collectively make computing image features a bit annoying. `enczoo` handles: 
+    
+* performing model-specific image normalization ("_was it -1 to 1, 0 to 1, 0-255...? ImageNet channel normalization...?_"),
+* correctly encoding images ("_my image was in mode L, not RGB!_")
+* turning off any batch normalization ("_was the model in training mode...?_")
+* extracting intermediate layers by name ("_how do I do that forward hook thing again...?_")
+* turning off autograd, and returning tensors as `np.ndarray` (no more `.cpu().numpy()`)
+* image cropping to fit input tensor shape (default: center cropping. no black bars!)
+* and more!

enczoo-0.1.0/README.md

@@ -0,0 +1,37 @@
+# `enczoo`: a zoo of encoding models for images
+
+[![CI](https://github.com/himjl/enczoo/actions/workflows/ci.yml/badge.svg)](https://github.com/himjl/enczoo/actions/workflows/ci.yml)
+
+`enczoo` is a Python library with a single goal: to map images (as `PIL.Images`) to intermediate representations (as `np.ndarray`) from off-the-shelf vision models, such as AlexNet and ResNet50.
+
+This library is meant for those who just need to compute off-the-shelf image features once for their project (and perhaps cache them elsewhere).
+
+### Installation
+
+`enczoo` requires Python 3.12 or above, and may be installed using [uv](https://docs.astral.sh/uv/) with the following command: 
+
+>`uv add enczoo`
+ 
+### Usage 
+
+```python
+import enczoo
+import PIL.Image
+image = PIL.Image.open('my-image.png')
+
+model = enczoo.ResNet50(layer_name='avgpool') # try layer4, layer3, ...
+features = model.compute_features(images=[image]) # np.ndarray
+
+# Want another layer? Check out: print(enczoo.ResNet50.layer_names)
+```
+
+### Things `enczoo` handles
+`enczoo` aims to "just work" by solving several tiny problems which collectively make computing image features a bit annoying. `enczoo` handles: 
+    
+* performing model-specific image normalization ("_was it -1 to 1, 0 to 1, 0-255...? ImageNet channel normalization...?_"),
+* correctly encoding images ("_my image was in mode L, not RGB!_")
+* turning off any batch normalization ("_was the model in training mode...?_")
+* extracting intermediate layers by name ("_how do I do that forward hook thing again...?_")
+* turning off autograd, and returning tensors as `np.ndarray` (no more `.cpu().numpy()`)
+* image cropping to fit input tensor shape (default: center cropping. no black bars!)
+* and more!

enczoo-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "enczoo"
+version = "0.1.0"
+description = "Map images (as `PIL.Images`) to intermediate representations (as `np.ndarray`) from off-the-shelf vision models."
+readme = "README.md"
+authors = [
+    { name = "himjl", email = "mil@mit.edu" }
+]
+license = { file = "LICENSE" }
+requires-python = ">=3.12"
+dependencies = [
+    "h5py>=3.15.1",
+    "pillow>=12.1.0",
+    "pydantic>=2.12.5",
+    "pytest>=9.0.2",
+    "torch>=2.9.1",
+    "torchvision>=0.24.1",
+    "tqdm>=4.67.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.12,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "black>=25.12.0",
+    "matplotlib>=3.10.8",
+    "pytest>=9.0.2",
+    "ruff>=0.14.10",
+    "ty>=0.0.9",
+]

enczoo-0.1.0/src/enczoo/__init__.py

@@ -0,0 +1,6 @@
+__all__ = ["ImageEncoding", "Pixels", "ResNet50", "AlexNet"]
+
+
+from enczoo.base import ImageEncoding
+from enczoo.neural_networks.pretrained import AlexNet, ResNet50
+from enczoo.classic.pixels import Pixels

enczoo-0.1.0/src/enczoo/base.py

@@ -0,0 +1,172 @@
+from abc import ABC, abstractmethod
+from typing import List, Tuple
+
+import PIL.Image
+import numpy as np
+import torch
+
+import enczoo.utils as utils
+
+
+# %%
+class ImageEncoding(
+    torch.nn.Module,
+    ABC,
+):
+    """Map PIL images to batched float tensors.
+
+    This module maps B-length lists of PIL.Image.Image to float tensors shaped
+    [B, *]. Parameters do not aggregate gradients by default.
+    """
+
+    def __init__(
+        self,
+        trainable: bool = False,
+    ):
+        """Initialize the encoder.
+
+        Args:
+            trainable: If True, the module is put in train mode.
+        """
+        super().__init__()
+        self.trainable = trainable
+        self._module_hash = None
+        self._tensor_bucket = None
+        self._output_shape = None
+
+        # Set the module's mode
+        self.train(mode=trainable)
+
+    @property
+    def device(self) -> torch.device:
+        """Infer the device from the first parameter or buffer.
+
+        Returns:
+            The device of the first parameter or buffer, or CPU if none exist.
+        """
+        try:
+            return next(self.parameters()).device
+        except StopIteration:
+            try:
+                return next(self.buffers()).device
+            except StopIteration:
+                return torch.device("cpu")
+
+    @property
+    def output_shape(self) -> Tuple[int, ...]:
+        """Return the output feature shape (excluding batch dimension)."""
+        if self._output_shape is None:
+            test_image = PIL.Image.fromarray(np.zeros((512, 512, 3), dtype=np.uint8))
+            test_result = self.compute_features(images=[test_image], flatten=False)
+            if not isinstance(test_result, np.ndarray):
+                raise ValueError(
+                    f"Expected a np.ndarray from self.forward, but got {type(test_result)}"
+                )
+            if not test_result.shape[0] == 1:
+                raise ValueError(
+                    f"Expected a batch size of 1, but got {test_result.shape}"
+                )
+            if len(test_result.shape) == 1:
+                output_shape = tuple()
+            else:
+                output_shape = test_result.shape[1:]
+
+            self._output_shape = tuple(output_shape)
+
+        return self._output_shape
+
+    @property
+    def module_hash(self) -> str:
+        """Return a stable hash for the module's parameters and structure."""
+        if self.trainable:
+            raise ValueError("Cannot hash a trainable model.")
+
+        # Turn off gradients for all parameters
+        for param in self.parameters():
+            param.requires_grad = False
+
+        # Hash self if unhashed
+        if self._module_hash is None:
+            self._module_hash = utils.hash_torch_module(module=self)
+        return self._module_hash
+
+    def compute_features(
+        self,
+        images: List[PIL.Image.Image],
+        flatten: bool = False,
+        seed: int | None = None,
+    ) -> np.ndarray:
+        """Compute features and return them as a NumPy array.
+
+        This is an alias for __call__ to help IDEs that do not recognize the
+        torch.nn.Module __call__ signature.
+
+        Args:
+            images: A B-length list of PIL.Image.Image.
+            flatten: If True, flatten the output to [B, d].
+            seed: Optional RNG seed for deterministic results.
+
+        Returns:
+            A NumPy array of shape [B, *], or [B, d] if flatten=True.
+
+        Raises:
+            ValueError: If the input images are invalid.
+        """
+
+        with torch.random.fork_rng():
+            if seed is not None:
+                torch.manual_seed(seed)
+                if torch.cuda.is_available():
+                    torch.cuda.manual_seed_all(seed)
+            with torch.no_grad():
+                torch_features: torch.Tensor = self(images=images, flatten=flatten)
+                numpy_features = torch_features.detach().cpu().numpy()
+        return numpy_features
+
+    def forward(
+        self,
+        images: List[PIL.Image.Image],
+        flatten: bool = False,
+    ) -> torch.Tensor:
+        """Compute features for a batch of images.
+
+        Args:
+            images: A B-length list of PIL.Image.Image.
+            flatten: If True, flatten the output to [B, d].
+
+        Returns:
+            A torch.Tensor of shape [B, *].
+
+        Raises:
+            ValueError: If the images list is empty or not image objects.
+        """
+        if not isinstance(images, list):
+            raise ValueError(
+                f"Expected a list of PIL.Image.Images, but got {type(images)}"
+            )
+        if len(images) == 0:
+            raise ValueError("Expected a non-empty list of PIL.Image.Images.")
+        if not isinstance(images[0], PIL.Image.Image):
+            raise ValueError(
+                f"Expected a list of PIL.Image.Images, but element 0 is a {type(images[0])}"
+            )
+
+        # Call the subclass implementation
+        feats = self._images_to_features(images=images)
+        if flatten:
+            # Flatten the features
+            feats = feats.reshape(feats.shape[0], -1)
+
+        return feats
+
+    @abstractmethod
+    def _images_to_features(self, images: List[PIL.Image.Image]) -> torch.Tensor:
+        """Convert images to features.
+
+        Args:
+            images: A list of PIL.Image.Image.
+
+        Returns:
+            A torch.Tensor of shape [B, *].
+        """
+        raise NotImplementedError

enczoo-0.1.0/src/enczoo/classic/pixels.py

@@ -0,0 +1,89 @@
+from typing import List
+
+import PIL.Image
+import torch
+import torchvision.transforms.v2 as v2
+
+from enczoo.base import ImageEncoding
+from enczoo.transforms.random_projection import RandomProjection
+
+
+# %%
+class Pixels(ImageEncoding):
+    """Encode images by their resized center-crop pixels."""
+
+    def __init__(
+        self,
+        size: int = 16,
+        random_projection_dim: int | None = None,
+        random_projection_seed: int | None = None,
+    ):
+        """Initialize the pixel encoder.
+
+        Args:
+            size: Output side length in pixels.
+            random_projection_dim: Optional output dimension for projection.
+            random_projection_seed: Seed for projection weights.
+        """
+        super().__init__()
+
+        # Register size tensor as buffer
+        self.register_buffer(
+            "size", torch.tensor(size, dtype=torch.int16, requires_grad=False)
+        )
+
+        # Transform
+        self.transforms = v2.Compose(
+            [
+                v2.ToImage(),
+                v2.RGB(),
+                v2.ToDtype(torch.uint8, scale=True),
+                v2.Resize(size=None, max_size=size, antialias=False),
+                v2.CenterCrop(size=size),
+                v2.ToDtype(torch.float32, scale=True),
+            ]
+        )
+
+        # Random projection
+        if random_projection_dim is not None:
+            if random_projection_dim > (size * size * 3):
+                raise ValueError(
+                    f"random_projection_dim must be less than or equal to size * size * 3={size * size * 3}!"
+                )
+
+            if random_projection_seed is None:
+                raise ValueError(
+                    "random_projection_seed must be provided if random_projection_dim is not None!"
+                )
+            self.random_projection = RandomProjection(
+                seed=random_projection_seed,
+                in_features=int(size * size * 3),
+                out_features=random_projection_dim,
+            )
+        else:
+            self.random_projection = None
+
+    def _images_to_features(self, images: List[PIL.Image.Image]) -> torch.Tensor:
+        """Convert images to pixel features.
+
+        Args:
+            images: A list of PIL.Image.Image.
+
+        Returns:
+            A torch.Tensor of shape [B, size, size, 3] or projected features.
+        """
+        # Apply the transformations to each image
+        transformed_images = [self.transforms(image.convert("RGB")) for image in images]
+
+        # Stack the transformed images into a single tensor
+        images_tensor = torch.stack(transformed_images)
+
+        # If random projection is enabled, apply it
+        if self.random_projection is not None:
+            return self.random_projection(
+                images_tensor.reshape(images_tensor.shape[0], -1)
+            )
+        else:
+            # Rearrange from BCHW to BHWC order
+            images_tensor = images_tensor.permute(0, 2, 3, 1)
+            return images_tensor

enczoo-0.1.0/src/enczoo/neural_networks/base.py

@@ -0,0 +1,184 @@
+from abc import ABC
+from typing import Dict, List, Tuple
+
+import PIL.Image
+import numpy as np
+import torch
+import torchvision
+
+from enczoo.base import ImageEncoding
+from enczoo.transforms.random_projection import RandomProjection
+
+
+class ImageNeuralNetwork(ImageEncoding, ABC):
+    """Image encoding backed by a torch neural network."""
+
+    def __init__(
+        self,
+        image_loader: torch.nn.Module | torchvision.transforms.Compose,
+        model: torch.nn.Module,
+        layer_name: str,
+        random_projection_dim: int | None,
+        random_projection_seed: int | None,
+    ):
+        """Initialize the neural network encoder.
+
+        Args:
+            image_loader: Module that converts PIL images to model inputs.
+            model: Torch model used to compute activations.
+            layer_name: Name of the layer whose activations are returned.
+            random_projection_dim: Optional output dimension for projection.
+            random_projection_seed: Seed for projection weights.
+
+        Raises:
+            ValueError: If the layer name is not found.
+        """
+        super().__init__()
+
+        # Ensure modules will be registered in evaluation mode
+        self.train(mode=False)
+
+        # Register buffers to ensure the model's hash is distinctive for each layer
+        self.register_buffer(
+            "layer_name", torch.tensor([ord(c) for c in layer_name], dtype=torch.int16)
+        )
+        self._layer_name = layer_name  # Needed for the forward pass
+
+        def register_hook(
+            module: torch.nn.Module,
+            root_name: str,
+            activations_dict: Dict[str, torch.Tensor],
+        ) -> List[str]:
+            """Recursively register forward hooks on leaf modules.
+
+            Args:
+                module: Module whose children are walked.
+                root_name: Prefix for module names.
+                activations_dict: Dict populated with layer activations.
+
+            Returns:
+                A list of layer names in discovery order.
+            """
+            module_names = []
+
+            nchildren = 0
+            for module_name, submodule in module.named_children():
+                if module_name != "":
+                    next_root_name = (
+                        root_name + "." + module_name
+                        if root_name != ""
+                        else module_name
+                    )
+                else:
+                    raise ValueError("Empty module name found in model!")
+                # Ensure module is in evaluation mode
+                submodule.train(mode=False)
+                # Recursive call:
+                submodule_names = register_hook(
+                    submodule,
+                    root_name=next_root_name,
+                    activations_dict=activations_dict,
+                )
+
+                # Update the number of children
+                nchildren += 1
+                module_names.extend(submodule_names)
+
+            # Base case:
+            if nchildren == 0:
+                layer_name = root_name
+
+                if layer_name in activations_dict:
+                    # Don't think this should ever happen:
+                    raise Exception(
+                        f"Layer name {layer_name} already exists in hidden activations! Existing keys: {self._hidden_activations.keys()}"
+                    )
+
+                def hook_function(module: torch.nn.Module, args, output):
+                    # print(f'Hook called on {layer_name}')
+                    activations_dict[layer_name] = output
+
+                # Attach forward hook
+                module.register_forward_hook(hook_function)
+
+                # Base case: no children
+                module_names.append(layer_name)
+            return module_names
+
+        # Register forward hooks that will populate this dictionary with hidden activations on the forward pass:
+        self._hidden_activations: Dict[str, torch.Tensor] = {}
+        self._layer_names = register_hook(
+            model, root_name="", activations_dict=self._hidden_activations
+        )
+
+        if layer_name not in self._layer_names:
+            raise ValueError(
+                f"Layer name {layer_name} not found in model.\nAvailable layer names: {self._layer_names}"
+            )
+
+        # Populate the sizes of the layers with a forward pass
+        with torch.no_grad():
+            test_image = PIL.Image.fromarray(np.zeros((224, 224, 3), dtype=np.uint8))
+            test_image = image_loader(test_image)
+            model(test_image.unsqueeze(0))
+
+        self._layer_to_shape = {
+            layer: tuple(self._hidden_activations[layer].shape[1:])
+            for layer in self._hidden_activations
+        }
+
+        # Register modules
+        self.image_loader = image_loader
+        self.model = model
+
+        if random_projection_dim is not None:
+            if random_projection_seed is None:
+                raise ValueError(
+                    "random_projection_seed must be provided if random_projection_dim is not None!"
+                )
+            self.random_projection = RandomProjection(
+                seed=random_projection_seed,
+                in_features=int(np.prod(self._layer_to_shape[layer_name])),
+                out_features=random_projection_dim,
+            )
+        else:
+            self.random_projection = None
+
+    def _images_to_features(self, images: List[PIL.Image.Image]) -> torch.Tensor:
+        """Convert images to network activations.
+
+        Args:
+            images: A list of PIL.Image.Image.
+
+        Returns:
+            A torch.Tensor of shape [B, *].
+        """
+
+        # Preprocess the images
+        preprocessed_images = torch.stack(
+            [self.image_loader(image) for image in images], dim=0
+        )
+
+        # Transfer to the correct device
+        preprocessed_images = preprocessed_images.to(self.device)
+
+        # Run the forward pass
+        self.model(preprocessed_images)
+
+        # Retrieve the activations for the given layer
+        f = self._hidden_activations[self._layer_name]
+
+        # Perform random projection if requested
+        if self.random_projection is not None:
+            # Flatten the features
+            f = f.reshape(f.shape[0], -1)
+
+            # Run the random projection forward
+            f = self.random_projection(f)
+
+        return f
+
+    @property
+    def layer_name_to_shape(self) -> Dict[str, Tuple[int, ...]]:
+        """Return a mapping of layer names to activation shapes."""
+        return self._layer_to_shape

enczoo-0.1.0/src/enczoo/neural_networks/pretrained.py

@@ -0,0 +1,163 @@
+from abc import ABC, abstractmethod
+from typing import List, Tuple
+
+import PIL.Image
+import torch
+import torchvision.models
+import torchvision.transforms.functional as F
+
+from enczoo.neural_networks.base import ImageNeuralNetwork
+
+
+class StandardImageLoader(torch.nn.Module):
+    """Load and normalize images for standard torchvision models.
+
+    This loader resizes directly to 224 before center-crop, preserving the
+    largest square sub-image. It also converts inputs to RGB.
+
+    Example:
+        - Original loader: resize to 256, then center-crop 224.
+        - This loader: resize to 224, then center-crop 224.
+    """
+
+    def forward(self, img: PIL.Image.Image) -> torch.Tensor:
+        """Convert a PIL image into a normalized tensor.
+
+        Args:
+            img: Input image.
+
+        Returns:
+            Normalized image tensor suitable for torchvision models.
+        """
+        img = img.convert("RGB")
+
+        img_tensor = F.pil_to_tensor(pic=img)
+        img_tensor = F.resize(
+            img=img_tensor, size=[224], interpolation=F.InterpolationMode.BILINEAR
+        )
+        img_tensor = F.center_crop(img=img_tensor, output_size=[224])
+        img_tensor = F.convert_image_dtype(image=img_tensor, dtype=torch.float)
+        img_tensor = F.normalize(
+            tensor=img_tensor,
+            mean=[0.485, 0.456, 0.406],
+            std=[0.229, 0.224, 0.225],
+        )
+        return img_tensor
+
+
+class _PretrainedNN(ImageNeuralNetwork, ABC):
+    """Base class for pretrained torchvision encoders."""
+
+    layer_names: List[str]
+
+    def __init__(
+        self,
+        layer_name: str,
+        random_projection_dim: int | None = None,
+        random_projection_seed: int | None = None,
+    ):
+        """Initialize a pretrained encoder.
+
+        Args:
+            layer_name: Name of the layer whose activations are returned.
+            random_projection_dim: Optional output dimension for projection.
+            random_projection_seed: Seed for projection weights.
+
+        Raises:
+            ValueError: If the layer name is invalid.
+        """
+        if layer_name not in self.layer_names:
+            raise ValueError(
+                f"Unknown layer_name: {layer_name}. Available:\n{self.layer_names}"
+            )
+
+        image_loader, model = self._load_modules()
+
+        # Ensure modules are in evaluation mode by default
+        image_loader.train(mode=False)
+        model.train(mode=False)
+
+        super().__init__(
+            image_loader=image_loader,
+            model=model,
+            layer_name=layer_name,
+            random_projection_dim=random_projection_dim,
+            random_projection_seed=random_projection_seed,
+        )
+
+    @abstractmethod
+    def _load_modules(self) -> Tuple[torch.nn.Module, torch.nn.Module]:
+        """Load the image loader and model for this network.
+
+        Returns:
+            A tuple of (image_loader, model).
+        """
+        raise NotImplementedError
+
+
+class AlexNet(_PretrainedNN):
+    """AlexNet encoder with named layer outputs."""
+
+    # A subset of all layers (each separated by one nonlinearity):
+    layer_names = [
+        "features.1",
+        "features.4",
+        "features.7",
+        "features.9",
+        "features.11",
+        "classifier.2",
+        "classifier.5",
+        "classifier.6",
+    ]
+
+    def _load_modules(self):
+        """Load the AlexNet image loader and model."""
+        image_loader = StandardImageLoader()
+        model = torchvision.models.alexnet(
+            weights=torchvision.models.AlexNet_Weights.IMAGENET1K_V1
+        )
+        return image_loader, model
+
+
+class ResNet50(_PretrainedNN):
+    """ResNet-50 encoder with named layer outputs."""
+
+    # A subset of layers (each separated by one nonlinearity, except layer4.2.relu, avgpool, and fc, which are connected by a linear layer):
+    layer_names = [
+        "relu",
+        "layer1.0.relu",
+        "layer1.1.relu",
+        "layer1.2.relu",
+        "layer2.0.relu",
+        "layer2.1.relu",
+        "layer2.2.relu",
+        "layer2.3.relu",
+        "layer3.0.relu",
+        "layer3.1.relu",
+        "layer3.2.relu",
+        "layer3.3.relu",
+        "layer3.4.relu",
+        "layer3.5.relu",
+        "layer4.0.relu",
+        "layer4.1.relu",
+        "layer4.2.relu",
+        "avgpool",
+        "fc",
+    ]
+
+    def _load_modules(self):
+        """Load the ResNet-50 image loader and model."""
+        image_loader = StandardImageLoader()
+        model = torchvision.models.resnet50(
+            weights=torchvision.models.ResNet50_Weights.IMAGENET1K_V1
+        )
+        return image_loader, model
+
+
+if __name__ == "__main__":
+    resnet50 = ResNet50(
+        layer_name="avgpool", random_projection_dim=None, random_projection_seed=0
+    )
+    print(resnet50.training)
+    print(resnet50.model.training)
+    print(getattr(resnet50.image_loader, "training", None))

enczoo-0.1.0/src/enczoo/neural_networks/tests/test_pretrained_nn.py

@@ -0,0 +1,54 @@
+from typing import List
+
+import PIL.Image
+import numpy as np
+import pytest
+import torch
+
+from enczoo import AlexNet
+
+
+@pytest.fixture
+def alexnet():
+    return AlexNet(
+        layer_name=AlexNet.layer_names[-1],
+        random_projection_dim=None,
+        random_projection_seed=0,
+    )
+
+
+@pytest.fixture
+def images() -> List[PIL.Image.Image]:
+    np.random.seed(0)
+    img_dat1 = PIL.Image.fromarray(
+        np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)
+    )
+    img_dat2 = PIL.Image.fromarray(
+        np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)
+    )
+    return [img_dat1, img_dat2]
+
+
+@pytest.fixture
+def image_batch1(images):
+    return [images[0]]
+
+
+@pytest.fixture
+def image_batch2(images):
+    return images
+
+
+def test_default_is_not_training(alexnet):
+    assert not alexnet.training
+
+
+def test_alexnet_forward(alexnet, image_batch1, image_batch2):
+    # Test output is deterministic
+    result = alexnet(images=image_batch1)
+    result2 = alexnet(images=image_batch1)
+    assert torch.allclose(result, result2)
+
+    # Test output does not depend on batch size
+    result_bigger_batch = alexnet(images=image_batch2)
+    assert torch.allclose(result[0], result_bigger_batch[0], rtol=1e-3)

enczoo-0.1.0/src/enczoo/transforms/random_projection.py

@@ -0,0 +1,73 @@
+import math
+from typing import Tuple, cast
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class RandomProjection(nn.Module):
+    """Apply a fixed random projection to an input tensor."""
+
+    def __init__(
+        self,
+        in_features: int,
+        out_features: int,
+        seed: int,
+    ):
+        """Initialize the random projection.
+
+        Args:
+            in_features: Input feature dimension.
+            out_features: Output feature dimension.
+            seed: Seed for the random projection weights.
+        """
+
+        super().__init__()
+        self.train(mode=False)
+
+        # Register inputs as buffers; these will constitute the module's hash.
+        self.register_buffer(
+            "seed", torch.tensor(seed, dtype=torch.int64, requires_grad=False)
+        )
+        self.register_buffer(
+            "in_features",
+            torch.tensor(in_features, dtype=torch.int64, requires_grad=False),
+        )
+        self.register_buffer(
+            "out_features",
+            torch.tensor(out_features, dtype=torch.int64, requires_grad=False),
+        )
+
+        with torch.random.fork_rng():
+            # Set the weights from a standard normal distribution:
+            torch.manual_seed(seed)
+            weights = torch.randn(
+                size=(out_features, in_features),
+                dtype=torch.float32,
+                requires_grad=False,
+            ) / math.sqrt(in_features * out_features)
+
+        self.register_buffer("projection_weights", weights)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Project input features with a fixed random matrix.
+
+        Args:
+            x: Input tensor of shape [B, in_features].
+
+        Returns:
+            Projected tensor of shape [B, out_features].
+        """
+        weights = cast(torch.Tensor, self.projection_weights)
+        return F.linear(x, weights)
+
+    def __repr__(self):
+        """Return a concise representation for debugging."""
+        return f"RandomProjection(in_features={self.in_features}, out_features={self.out_features}, seed={self.seed})"
+
+    @property
+    def output_shape(self) -> Tuple[int]:
+        """Return the output feature shape (excluding batch dimension)."""
+        weights = cast(torch.Tensor, self.projection_weights)
+        return (weights.shape[0],)

enczoo-0.1.0/src/enczoo/utils.py

@@ -0,0 +1,60 @@
+import hashlib
+import itertools
+from typing import Iterable, Iterator, List, TypeVar
+
+import torch
+
+T = TypeVar("T")
+
+
+def iterate_batches(iterable: Iterable[T], batch_size: int) -> Iterator[List[T]]:
+    """Yield items from an iterable in fixed-size batches.
+
+    Args:
+        iterable: Source iterable to batch.
+        batch_size: Number of items per batch.
+
+    Yields:
+        Lists of up to batch_size elements.
+
+    Raises:
+        ValueError: If batch_size is less than 1.
+    """
+    if batch_size < 1:
+        raise ValueError("Batch size must be at least 1!")
+
+    iterator = iter(iterable)
+    while True:
+        batch = list(itertools.islice(iterator, batch_size))
+        if len(batch) == 0:
+            return
+        yield batch
+
+
+def hash_torch_module(module: torch.nn.Module) -> str:
+    """Return a hash for a torch.nn.Module.
+
+    The hash depends on the module's state_dict and string representation.
+
+    Args:
+        module: Module to hash.
+
+    Returns:
+        Hex-encoded SHA-256 hash.
+    """
+
+    sha256_hash = hashlib.sha256()
+
+    # Hash the model's state_dict:
+    state_dict = module.state_dict()
+    for key in sorted(state_dict.keys()):
+        tensor_value = state_dict[key].detach().cpu().numpy()
+        sha256_hash.update(tensor_value.tobytes())
+
+    # Hash the module's string representation:
+    module_string = str(module)
+    module_string = module_string.encode("utf-8")
+    sha256_hash.update(module_string)
+
+    # Return the combined hash:
+    return sha256_hash.hexdigest()