Initial commit

Author: Anton Hosgood

.github/workflows/ruff-format-check.yml

@@ -0,0 +1,22 @@
+name: Ruff
+
+on: [ push ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.13"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+      - name: Check formatting
+        run: |
+          ruff check .
+          ruff check --select I .
+          ruff format --check .

.gitignore

@@ -0,0 +1,167 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Generated datasets
+data/
+!src/data/
+
+# Model checkpoints
+checkpoints/

notebooks/demo.ipynb

@@ -0,0 +1,7 @@
+requests~=2.32.3
+torch~=2.7.0
+pillow~=11.2.1
+torchvision~=0.22.0
+matplotlib~=3.10.3
+tqdm~=4.67.1
+PyYAML~=6.0.2

requirements.txt

@@ -0,0 +1,44 @@
+import argparse
+from pathlib import Path
+
+from src.api.lorem_picsum import LoremPicsum
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("output", type=str)
+    parser.add_argument("width", type=int)
+    parser.add_argument("height", type=int)
+
+    args = parser.parse_args()
+    width = args.width
+    height = args.height
+
+    output_path = Path(args.output)
+    dataset_dir = f"stock_images_{width}x{height}"
+    color_image_dir = output_path / dataset_dir / "color"
+    grayscale_image_dir = output_path / dataset_dir / "grayscale"
+
+    color_image_dir.mkdir(parents=True, exist_ok=True)
+    grayscale_image_dir.mkdir(parents=True, exist_ok=True)
+
+    api = LoremPicsum(width, height)
+    image_ids = LoremPicsum.get_image_ids()
+
+    # Iterate through image_ids instead of a range as some IDs are missing
+    for idx, image_id in enumerate(image_ids):
+        color_output_path = color_image_dir / f"{idx}.jpg"
+        grayscale_output_path = grayscale_image_dir / f"{idx}.jpg"
+
+        api.download_image(color_output_path, image_id, grayscale=False)
+        api.download_image(grayscale_output_path, image_id, grayscale=True)
+
+        print(
+            f"Image {image_id} successfully downloaded ({idx + 1} / {len(image_ids)})"
+        )
+
+    print("All done.")
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_dataset.py

@@ -0,0 +1,112 @@
+import time
+from os import PathLike
+from typing import AnyStr, List, Optional
+
+import requests
+
+
+class LoremPicsum:
+    """A utility class to interact with the Lorem Picsum API for downloading placeholder images."""
+
+    API = "https://picsum.photos"
+    PAGE_LIMIT = 100
+
+    def __init__(self, width: int, height: int) -> None:
+        """
+        Initializes an instance of the LoremPicsum class with specific image dimensions.
+
+        Args:
+            width: The width of images to be downloaded.
+            height: The height of images to be downloaded.
+        """
+        self.width = width
+        self.height = height
+
+    def download_image(
+        self,
+        path: PathLike[AnyStr] | AnyStr,
+        image_id: Optional[int] = None,
+        grayscale: bool = False,
+        blur: Optional[int] = None,
+        retries: int = 3,
+    ) -> None:
+        """
+        Downloads a JPEG image from the Lorem Picsum API and saves it to a file.
+
+        Args:
+            path: The path the output image will be saved to.
+            image_id: The ID of the image to download (default is None). If not provided, a random image will be
+              downloaded.
+            grayscale: Whether to download the image in grayscale (default is False).
+            blur: The blur level of the image (default is None). If provided, it should be an integer between 1 and 10
+              indicating the level of blur.
+            retries: The number of times to retry the request (default is 3).
+
+        Raises:
+            requests.exceptions.RequestException: If the HTTP request to download the image fails.
+        """
+        url = self.build_url(image_id)
+
+        params = {
+            "grayscale": True if grayscale else None,
+            "blur": blur if blur else None,
+        }
+
+        for attempt in range(retries + 1):
+            try:
+                response = requests.get(url, params=params)
+                response.raise_for_status()
+                break
+            except requests.exceptions.RequestException:
+                if attempt == retries:
+                    raise
+                time.sleep(1)
+
+        with open(path, "wb") as f:
+            f.write(response.content)
+
+    def build_url(self, image_id: Optional[int] = None) -> str:
+        """
+        Builds the URL for downloading an image from the Lorem Picsum API.
+
+        Args:
+            image_id: The ID of the image to be included in the URL (default is None). If provided, it will specify a
+              particular image.
+
+        Returns:
+            str: The complete URL for the image download.
+        """
+        url = self.API
+
+        if image_id is not None:
+            url += f"/id/{image_id}"
+
+        url += f"/{self.width}/{self.height}"
+        return url
+
+    @staticmethod
+    def get_image_ids() -> List[int]:
+        """
+        Returns a list of ids of images available in the Lorem Picsum API.
+
+        When downloading all images, iterate through the returned image IDs instead of a range as some IDs are missing.
+
+        Raises:
+            requests.exceptions.RequestException: If the HTTP request to retrieve the image list fails.
+        """
+        ids = []
+        page = 1
+        url = f"{LoremPicsum.API}/v2/list"
+
+        while True:
+            response = requests.get(
+                url, params={"page": page, "limit": LoremPicsum.PAGE_LIMIT}
+            )
+            response.raise_for_status()
+
+            results = response.json()
+            if len(results) == 0:
+                return ids
+
+            ids += [int(x["id"]) for x in results]
+            page += 1