Iris Unlock Implementation Guide — Steps &
Code
Purpose: This document is a complete, step-by-step guide you can run in Jupyter or Google Colab to
build an iris-based unlock system. It contains environment setup, dataset download instructions,
classical and deep-learning pipelines (with runnable code snippets), training tips, evaluation, and
deployment notes. Export this document as PDF from the editor when ready.
Table of Contents
1. Prerequisites
2. Quick plan (overview)
3. Environment setup (Jupyter / Colab)
4. Getting a public iris dataset (Kaggle / Drive)
5. Classical pipeline (segmentation → normalization → iris code → match)
6. segmentation code
7. normalization (rubber-sheet)
8. simple feature baseline (LBP) and Gabor outline
9. matching (Hamming / simple similarity)
10. Deep Learning pipeline (segmentation model + embedding model)
11. dataset class & transforms
12. Siamese / contrastive model (PyTorch)
13. training loop
14. evaluation (ROC, EER)
15. Liveness / anti-spoofing notes
16. Template storage & deployment
17. Exporting & packaging (how to make the PDF)
18. Appendix: Colab-specific commands and tips
1. Prerequisites
• Comfortable with Python (numpy, OpenCV).
• Familiar with PyTorch (or willing to adapt TF code).
• A GPU is recommended for deep learning (Colab GPU is fine).
• Dataset: CASIA/IITD/UBIRIS or a custom dataset of labeled iris images.
2. Quick plan (overview)
1. Acquire dataset.
2. Classical baseline: detect pupil/iris → normalize → extract simple features → match.
3. Deep baseline: train segmentation (optional) and a metric-learning model (Siamese/Triplet/
ArcFace) to get embeddings.
4. Evaluate with ROC/EER, tune threshold for verification.
5. Add liveness checks and deploy templates (encrypted).
1
3. Environment setup (Jupyter / Colab)
Colab: enable GPU: Runtime → Change runtime type → GPU.
Install required packages (run in a notebook cell):
!pip install -q opencv-python-headless==4.7.0.72 torch torchvision
torchaudio --extra-index-url https://download.pytorch.org/whl/cu118
!pip install -q timm albumentations matplotlib scikit-learn kaggle
Mount Google Drive (if you store dataset there):
from google.colab import drive
drive.mount('/content/drive')
If using Kaggle datasets, upload kaggle.json or set the Kaggle API token and download:
!mkdir -p ~/.kaggle
# upload kaggle.json in Files and then
!cp /content/kaggle.json ~/.kaggle/
!chmod 600 ~/.kaggle/kaggle.json
!kaggle datasets download -d <dataset-slug> -p /content/data
!unzip /content/data/*.zip -d /content/data
4. Getting a public iris dataset
Search Kaggle or institutional websites for: CASIA Iris , IITD Iris , ND-IRIS-0405 , UBIRIS .
Download and extract into /content/data/iris/ and inspect file structure.
Example to list files:
import os
for root, dirs, files in os.walk('/content/data/iris'):
print(root, len(files))
break
5. Classical pipeline
This pipeline is fast to prototype and gives a baseline. It consists of: - segmentation to find pupil center
and iris boundary - normalization (rubber-sheet transform) - feature extraction (LBP/Gabor) - matching
via Hamming or simple distance
2
5.1 Segmentation (simple Hough-based)
import cv2
import numpy as np
def find_pupil_iris(img_gray):
# img_gray: single-channel grayscale
img = cv2.medianBlur(img_gray, 5)
# find pupil: dark circular area
_, th = cv2.threshold(img, 50, 255, cv2.THRESH_BINARY_INV)
circles = cv2.HoughCircles(th, cv2.HOUGH_GRADIENT, dp=1.5, minDist=50,
param1=50, param2=30, minRadius=10,
maxRadius=80)
if circles is None:
return None
x, y, r = map(int, circles[0][0])
iris_r = int(r * 2.5)
return x, y, r, iris_r
Note: This is a simple heuristic and will fail on many images — replace with a better edge-
based Hough or a learned U-Net for production.
5.2 Normalization (rubber-sheet transform)
def normalize_iris(img_gray, cx, cy, pup_r, iris_r, radial_res=64,
angular_res=256):
h, w = img_gray.shape
angles = np.linspace(0, 2*np.pi, angular_res)
radii = np.linspace(pup_r, iris_r, radial_res)
normalized = np.zeros((radial_res, angular_res), dtype=np.uint8)
for i, ri in enumerate(radii):
for j, a in enumerate(angles):
x = int(cx + ri * np.cos(a))
y = int(cy + ri * np.sin(a))
x = np.clip(x, 0, w-1)
y = np.clip(y, 0, h-1)
normalized[i, j] = img_gray[y, x]
return normalized
5.3 Simple feature baseline (LBP) & matching
from skimage.feature import local_binary_pattern
def iris_lbp_code(norm_img, P=8, R=1):
# norm_img: 2D normalized iris
lbp = local_binary_pattern(norm_img, P, R, method='uniform')
# flatten & histogram as compact descriptor
hist, _ = np.histogram(lbp.ravel(), bins=np.arange(0, P+3), density=True)
3
return hist
# similarity
def cosine_sim(a,b):
return np.dot(a,b)/(np.linalg.norm(a)*np.linalg.norm(b)+1e-8)
This baseline gives a quick verification system using cosine similarity and thresholding.
5.4 Gabor / Daugman iris code (outline)
Gabor-based iris code implementation is longer — look up Daugman's iris code papers or published
code. The steps: 1. Apply a bank of 2D Gabor filters to normalized iris. 2. Quantize phase responses into
bits (0/1) → produce binary code. 3. Match using masked Hamming distance (ignore occluded pixels).
6. Deep Learning pipeline (recommended for high accuracy)
This section provides runnable PyTorch snippets for a Siamese/contrastive approach. It assumes you
have normalized iris images (or you can train end-to-end from cropped images).
6.1 Dataset & transforms
import torch
from torch.utils.data import Dataset
from torchvision import transforms
class IrisPairDataset(Dataset):
def __init__(self, image_paths, labels, transform=None,
pairs_per_epoch=10000):
# image_paths: list of file paths
# labels: list of corresponding person IDs (ints or strings)
self.paths = image_paths
self.labels = labels
self.transform = transform
self.pairs_per_epoch = pairs_per_epoch
# build index per label
from collections import defaultdict
self.by_label = defaultdict(list)
for p, l in zip(self.paths, self.labels):
self.by_label[l].append(p)
self.labels_list = list(self.by_label.keys())
def __len__(self):
return self.pairs_per_epoch
def __getitem__(self, idx):
import random
# 50/50 positive/negative
if random.random() < 0.5:
4
lbl = random.choice(self.labels_list)
a, b = random.sample(self.by_label[lbl], 2)
label = 1
else:
l1, l2 = random.sample(self.labels_list, 2)
a = random.choice(self.by_label[l1])
b = random.choice(self.by_label[l2])
label = 0
from PIL import Image
ia = Image.open(a).convert('L')
ib = Image.open(b).convert('L')
if self.transform:
ia = self.transform(ia)
ib = self.transform(ib)
return ia, ib, torch.tensor(label, dtype=torch.float32)
transform = transforms.Compose([
transforms.Resize((224,224)),
transforms.ToTensor(),
transforms.Normalize([0.5], [0.5])
])
6.2 Siamese model (ResNet backbone)
import torch.nn as nn
import torchvision.models as models
class SiameseNet(nn.Module):
def __init__(self, out_dim=128, pretrained=True):
super().__init__()
backbone = models.resnet18(pretrained=pretrained)
# adapt for 1-channel input
backbone.conv1 = nn.Conv2d(1, 64, kernel_size=7, stride=2, padding=3,
bias=False)
modules = list(backbone.children())[:-1]
self.encoder = nn.Sequential(*modules)
self.fc = nn.Sequential(
nn.Flatten(),
nn.Linear(512,256),
nn.ReLU(),
nn.Linear(256,out_dim)
)
def forward_once(self,x):
out = self.encoder(x)
out = self.fc(out)
out = out / (out.norm(dim=1, keepdim=True) + 1e-8)
return out
def forward(self,x1,x2):
return self.forward_once(x1), self.forward_once(x2)
5
6.3 Contrastive loss and training loop
import torch.optim as optim
class ContrastiveLoss(nn.Module):
def __init__(self, margin=1.0):
super().__init__()
self.margin = margin
def forward(self, out1, out2, label):
dist_sq = (out1 - out2).pow(2).sum(1)
# label==1 -> same -> minimize dist_sq
pos_loss = label * dist_sq
# label==0 -> different -> maximize up to margin
neg_loss = (1-label) * (torch.clamp(self.margin - torch.sqrt(dist_sq
+ 1e-8), min=0.0).pow(2))
return (pos_loss + neg_loss).mean()
# training skeleton
model = SiameseNet(out_dim=128).to(device)
criterion = ContrastiveLoss(margin=1.0)
optimizer = optim.AdamW(model.parameters(), lr=1e-4)
for epoch in range(1, num_epochs+1):
model.train()
running_loss = 0.0
for i, (a,b,label) in enumerate(train_loader):
a = a.to(device); b = b.to(device); label = label.to(device)
out1, out2 = model(a,b)
loss = criterion(out1,out2,label)
optimizer.zero_grad(); loss.backward(); optimizer.step()
running_loss += loss.item()
print(f"Epoch {epoch} loss {running_loss/len(train_loader):.4f}")
# TODO: validate and compute ROC/EER on validation pairs
6.4 Evaluation (pairs → ROC & EER)
import numpy as np
from sklearn.metrics import roc_curve
def compute_embeddings(model, loader):
model.eval()
embs = []
labels = []
paths = []
with torch.no_grad():
for x,y in loader: # assume loader gives images+labels for single
images
x = x.to(device)
e = model.forward_once(x)
6
embs.append(e.cpu().numpy())
labels.extend(y.numpy())
embs = np.vstack(embs)
return embs, np.array(labels)
# For pair-based evaluation keep distances and labels
# compute roc
fpr, tpr, thresholds = roc_curve(labels, scores)
fnr = 1 - tpr
eer_idx = np.nanargmin(np.abs(fnr - fpr))
eer = (fpr[eer_idx] + fnr[eer_idx]) / 2
print('EER:', eer)
Note: you must build proper pair generation for validation (list of positive and negative
pairs from held-out subjects).
7. Liveness / anti-spoofing notes
• Train a lightweight binary classifier (real vs spoof) using images/videos of printed eyes, screen
replays, etc.
• Use temporal cues (blink detection) or active challenge-response (ask user to look left/right).
• Multispectral imaging (NIR + visible) improves spoof detection.
8. Template storage & deployment
• Save L2-normalized float embeddings per user (one or multiple per user for robustness) in an
encrypted file or DB.
• For matching, compute cosine similarity with stored templates and accept if > threshold.
• For 1:N large-scale systems, use FAISS (approx nearest neighbor) for speed.
• Secure templates at rest (AES-256) and secure keys (KMS/HSM) — do not store raw images.
Example save/load embeddings:
import pickle
with open('templates.pkl','wb') as f:
pickle.dump({'user1': [emb1, emb2], 'user2': [emb3]}, f)
# load and match
with open('templates.pkl','rb') as f:
db = pickle.load(f)
9. Exporting & packaging (how to make the PDF)
• In JupyterLab: File → Export Notebook As → PDF (or print to PDF from the browser).
7
• In Google Colab: File → Print → Save as PDF OR copy the notebook into Drive and download as
.ipynb , then use nbconvert on your machine:
jupyter nbconvert --to pdf notebook.ipynb
• This document (in the canvas) can be exported as a PDF using the editor's export/download
option.
10. Appendix: Colab-ready minimal cells
1. Install & mount
!pip install -q opencv-python-headless==4.7.0.72 torch torchvision timm
albumentations scikit-learn
from google.colab import drive
drive.mount('/content/drive')
1. Download dataset via Kaggle (see Section 3)
2. Run segmentation & normalization cell (copy functions from Section 5)
3. Prepare pairs dataset and train (copy Dataset + model + training loop)
4. Evaluate and save templates
Closing notes & suggestions
• Start with the classical baseline first (Sections 5.1–5.3). It helps you verify dataset quality and
build the normalization pipeline.
• Move to the deep metric-learning approach (Section 6) for higher accuracy; use transfer learning
and strong augmentations.
• Add liveness detection as a separate module and fuse the result with verification to improve
security.
• For production, secure template storage and key management are absolutely required.
If you want, I can convert this document into a formatted PDF file for direct download, or produce a runnable
Colab .ipynb notebook with the exact cells ready to run. Tell me which one you prefer.
