Deep Learning › Convolutional Networks and Vision › Day 217
Hands-on lab — Day 217: Your Own Image Classifier
- ← Back to the Day 217 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/deep-learning/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
- Verify
calculate_simple_phashproduces 64-bit strings and 0 distance for identical images. - Confirm
generate_error_galleryranks the highest-confidence misclassification first. - 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
- Implement Grad-CAM activation mapping overlays for error gallery samples.
- Export the fine-tuned classifier to ONNX and benchmark INT8 quantization latency.
Navigation
- 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-classifierwhen 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
- 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.