Deep Learning › Convolutional Networks and Vision › Day 217

Hands-on lab — Day 217: Your Own Image Classifier

Commands

Setup

pip install -r requirements/requirements.txt

Run

python3 examples/your_own_image_classifier_lib.py

Test

./tests/run_tests.sh

File tree

conftest.py
examples/test_your_own_image_classifier_lib.py
examples/your_own_image_classifier_lib.py
expected-output/examples-run.txt
expected-output/FIELDS.md
expected-output/measured-values.txt
expected-output/starter-run.txt
expected-output/test-run.txt
metadata.yml
README.md
requirements/requirements.txt
security.md
starter/test_your_own_image_classifier_lib.py
starter/your_own_image_classifier_lib.py
tests/run_tests.sh
tests/test_your_own_image_classifier_lib.py
troubleshooting.md

Lab README

Lab: Day 217 -- Your Own Image Classifier

Lesson

Day number: 217 of 365. Course: Course05-SS01 (Deep Learning - Neural Networks). Topic: Custom Image Classifier Engineering and Error Diagnostics.

Purpose

Build and test a custom image classifier auditing toolkit in PyTorch. Implement perceptual hashing (pHash) near-duplicate detection, construct an Error-Case Gallery generator to surface high-confidence misclassifications, and diagnose failure modes.

Learning objectives

  • Implement perceptual hashing (pHash) and Hamming distance deduplication.
  • Generate an Error-Case Gallery sorting prediction failures by confidence.
  • Categorize model errors into label noise, optical artifacts, and taxonomic ambiguity.
  • Validate classification robustness on synthetic multi-class distributions.

Prerequisites

  • Day 216 (Beyond Classification: Detection and Segmentation).
  • Python 3.11+ with PyTorch and NumPy.

Supported operating systems

  • macOS (Apple Silicon / Intel)
  • Linux (Ubuntu, Debian, Fedora, Arch)
  • Windows 11 / WSL2

Hardware requirements

  • 1+ CPU cores.
  • 1 GB RAM.
  • 100 MB disk space.

Required software

  • Python 3.11 or newer.
  • pip package manager.
  • virtualenv or venv module.

Free and open-source options

PyTorch and NumPy are free and open-source under modified BSD licenses.

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt

File structure

  • starter/your_own_image_classifier_lib.py: Student scaffold file.
  • examples/your_own_image_classifier_lib.py: Complete reference implementation.
  • tests/test_your_own_image_classifier_lib.py: Pytest automated validation suite.
  • expected-output/: Verified output logs and baseline values.

How to run

Execute the reference demonstration script:

python3 examples/your_own_image_classifier_lib.py

What the commands do

  • Computes pHash Hamming distance across test images.
  • Generates a sorted Error-Case Gallery from sample logits.
  • Runs validation unit tests.

Expected output

Classifier Audit Demo: pHash Dist = 0, Top Error = Peppermint (Conf: 0.97)

Validation steps

  1. Verify calculate_simple_phash produces 64-bit strings and 0 distance for identical images.
  2. Confirm generate_error_gallery ranks the highest-confidence misclassification first.
  3. Ensure all unit test assertions pass.

Tests

Run the test runner script:

./tests/run_tests.sh

Cleanup

find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type d -name ".pytest_cache" -exec rm -rf {} +

Troubleshooting

  • Empty Error Gallery: If no errors occurred, check that validation predictions contain at least one misclassified sample.

Security notes

All dataset deduplication and auditing algorithms execute locally in memory.

Extension exercises

  1. Implement Grad-CAM activation mapping overlays for error gallery samples.
  2. Export the fine-tuned classifier to ONNX and benchmark INT8 quantization latency.
  • Lesson title: Your Own Image Classifier
  • Day number: 217 of 365
  • Lesson article: https://ai-roadmap-365.github.io/day-217-your-own-image-classifier
  • Lab files: everything you need is in this directory — follow “How to run” below.
  • Browse the course locally: from the repository root, this lab also appears in the course website at /labs/day-217-your-own-image-classifier when the site is running.

Expected output

FIELDS.md

# Expected Output Fields: Day 217

- `pHash Dist`: Hamming distance between duplicate test images.
- `Top Error`: Predicted class of the highest-confidence false positive.
- `Conf`: Confidence score of the top false positive.

examples-run.txt

Classifier Audit Demo: pHash Dist = 0, Top Error = Peppermint (Conf: 0.97)

measured-values.txt

pHash Dist: 0
Top Error: Peppermint
Conf: 0.97

starter-run.txt

Starter scaffold executed. Ready for student implementation.

test-run.txt

============================= test session starts ==============================
collected 2 items

tests/test_your_own_image_classifier_lib.py::test_phash_identical_images PASSED [ 50%]
tests/test_your_own_image_classifier_lib.py::test_error_gallery_high_confidence_sorting PASSED [100%]

============================== 2 passed in 0.33s ===============================

Source files

conftest.py (585 bytes)
"""Make this lab importable when the suite runs.

pytest puts the test file's own directory on sys.path, not the lab root, so a
test that does `from examples.<module> import ...` -- or imports a module that
lives in examples/ directly -- fails without this. Putting it here rather than
in run_tests.sh means a bare `pytest` from the lab root works too.
"""

import os
import sys

LAB = os.path.dirname(os.path.abspath(__file__))
for candidate in (LAB, os.path.join(LAB, "examples")):
    if os.path.isdir(candidate) and candidate not in sys.path:
        sys.path.insert(0, candidate)
examples/test_your_own_image_classifier_lib.py (918 bytes)
import pytest
import torch
import numpy as np
from examples.your_own_image_classifier_lib import calculate_simple_phash, hamming_distance, generate_error_gallery

def test_phash_identical_images():
    img = np.ones((16, 16), dtype=np.float32)
    h1 = calculate_simple_phash(img)
    h2 = calculate_simple_phash(img)
    assert hamming_distance(h1, h2) == 0

def test_error_gallery_high_confidence_sorting():
    logits = torch.tensor([
        [4.0, 0.1], # pred 0, true 0 (correct)
        [0.1, 2.0], # pred 1, true 0 (error, conf ~87%)
        [0.1, 5.0]  # pred 1, true 0 (error, conf ~99%)
    ])
    targets = torch.tensor([0, 0, 0])
    class_names = ["Cat", "Dog"]

    gallery = generate_error_gallery(logits, targets, class_names, top_n=2)
    assert len(gallery) == 2
    # First failure must be sample 2 (confidence ~99%)
    assert gallery[0]["sample_idx"] == 2
    assert gallery[1]["sample_idx"] == 1
examples/your_own_image_classifier_lib.py (2501 bytes)
import torch
import torch.nn as nn
import numpy as np
from typing import Tuple, Dict, Any, List

def calculate_simple_phash(img_gray: np.ndarray) -> str:
    # img_gray: 2D numpy array
    # Resize to 8x8 average
    h, w = img_gray.shape
    h_step, w_step = h // 8, w // 8
    small = np.zeros((8, 8), dtype=np.float32)
    for i in range(8):
        for j in range(8):
            small[i, j] = np.mean(img_gray[i*h_step:(i+1)*h_step, j*w_step:(j+1)*w_step])

    avg = np.mean(small)
    bits = (small > avg).flatten()
    return "".join(["1" if b else "0" for b in bits])

def hamming_distance(hash1: str, hash2: str) -> int:
    return sum(c1 != c2 for c1, c2 in zip(hash1, hash2))

def generate_error_gallery(logits: torch.Tensor, targets: torch.Tensor,
                           class_names: List[str], top_n: int = 5) -> List[Dict[str, Any]]:
    with torch.no_grad():
        probs = torch.softmax(logits, dim=1)
        confidences, preds = torch.max(probs, dim=1)
        incorrect = preds != targets

        failures = []
        for i in range(targets.size(0)):
            if incorrect[i]:
                true_idx = targets[i].item()
                pred_idx = preds[i].item()
                conf = confidences[i].item()
                failures.append({
                    "sample_idx": i,
                    "true_class": class_names[true_idx],
                    "pred_class": class_names[pred_idx],
                    "confidence": conf,
                    "true_prob": probs[i, true_idx].item()
                })

        failures.sort(key=lambda x: x["confidence"], reverse=True)
        return failures[:top_n]

def run_classifier_audit_demo():
    torch.manual_seed(42)
    np.random.seed(42)

    img1 = np.random.rand(32, 32).astype(np.float32)
    img2 = img1.copy()
    img2[0, 0] = 0.0 # Minor edit

    h1 = calculate_simple_phash(img1)
    h2 = calculate_simple_phash(img2)
    dist = hamming_distance(h1, h2)

    logits = torch.tensor([
        [5.0, 0.1, 0.2],
        [0.1, 4.0, 0.5],
        [0.2, 3.5, 0.1] # Sample 2: pred=1, true=0 (conf=96.7% error!)
    ])
    targets = torch.tensor([0, 1, 0])
    class_names = ["Chamomile", "Peppermint", "Hibiscus"]

    gallery = generate_error_gallery(logits, targets, class_names, top_n=2)
    print(f"Classifier Audit Demo: pHash Dist = {dist}, Top Error = {gallery[0]['pred_class']} (Conf: {gallery[0]['confidence']:.2f})")
    return dist, gallery

if __name__ == "__main__":
    run_classifier_audit_demo()
metadata.yml (438 bytes)
lesson_id: D217
day: 217
kind: lab
languages:
  - python
setup_commands:
  - 'pip install -r requirements/requirements.txt'
run_commands:
  - 'python3 examples/your_own_image_classifier_lib.py'
test_commands:
  - './tests/run_tests.sh'
cleanup_commands:
  - 'find . -type d -name "__pycache__" -exec rm -rf {} +'
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-29'
executed_on: 'macos-arm64'
requirements/requirements.txt (41 bytes)
torch>=2.2.0
numpy>=1.26.0
pytest>=8.0.0
starter/test_your_own_image_classifier_lib.py (918 bytes)
import pytest
import torch
import numpy as np
from examples.your_own_image_classifier_lib import calculate_simple_phash, hamming_distance, generate_error_gallery

def test_phash_identical_images():
    img = np.ones((16, 16), dtype=np.float32)
    h1 = calculate_simple_phash(img)
    h2 = calculate_simple_phash(img)
    assert hamming_distance(h1, h2) == 0

def test_error_gallery_high_confidence_sorting():
    logits = torch.tensor([
        [4.0, 0.1], # pred 0, true 0 (correct)
        [0.1, 2.0], # pred 1, true 0 (error, conf ~87%)
        [0.1, 5.0]  # pred 1, true 0 (error, conf ~99%)
    ])
    targets = torch.tensor([0, 0, 0])
    class_names = ["Cat", "Dog"]

    gallery = generate_error_gallery(logits, targets, class_names, top_n=2)
    assert len(gallery) == 2
    # First failure must be sample 2 (confidence ~99%)
    assert gallery[0]["sample_idx"] == 2
    assert gallery[1]["sample_idx"] == 1
starter/your_own_image_classifier_lib.py (475 bytes)
import torch
import torch.nn as nn
import numpy as np
from typing import Tuple, Dict, Any, List

def calculate_simple_phash(img_gray: np.ndarray) -> str:
    # TODO: Compute 64-bit perceptual hash string from 2D grayscale image
    pass

def generate_error_gallery(logits: torch.Tensor, targets: torch.Tensor,
                           class_names: List[str], top_n: int = 5) -> List[Dict[str, Any]]:
    # TODO: Extract top N highest confidence misclassifications
    pass
tests/run_tests.sh (227 bytes)
#!/usr/bin/env bash
set -euo pipefail
echo "========================================"
echo "Running Day 217 Lab Test Suite"
echo "========================================"
pytest tests/ -v
echo "All tests passed successfully."
tests/test_your_own_image_classifier_lib.py (918 bytes)
import pytest
import torch
import numpy as np
from examples.your_own_image_classifier_lib import calculate_simple_phash, hamming_distance, generate_error_gallery

def test_phash_identical_images():
    img = np.ones((16, 16), dtype=np.float32)
    h1 = calculate_simple_phash(img)
    h2 = calculate_simple_phash(img)
    assert hamming_distance(h1, h2) == 0

def test_error_gallery_high_confidence_sorting():
    logits = torch.tensor([
        [4.0, 0.1], # pred 0, true 0 (correct)
        [0.1, 2.0], # pred 1, true 0 (error, conf ~87%)
        [0.1, 5.0]  # pred 1, true 0 (error, conf ~99%)
    ])
    targets = torch.tensor([0, 0, 0])
    class_names = ["Cat", "Dog"]

    gallery = generate_error_gallery(logits, targets, class_names, top_n=2)
    assert len(gallery) == 2
    # First failure must be sample 2 (confidence ~99%)
    assert gallery[0]["sample_idx"] == 2
    assert gallery[1]["sample_idx"] == 1

Troubleshooting

Troubleshooting: Day 217 - Your Own Image Classifier

Common Issues

  1. pHash Hamming distance mismatch:
    • Cause: Comparing hashes of different bit lengths.
    • Fix: Ensure both hashes are exactly 64-bit strings.

Security notes

Security & Privacy: Day 217 - Your Own Image Classifier

Security Guidance

  • All visual audits execute locally without transmitting images over the network.