Eigenfaces — User Guide &
Technical Documentation

Three commands in Git Bash are all you need. Make sure all project files are in the same folder before starting.

pip install scikit-learn numpy pillow

cd /c/Users/YourName/Downloads/eigenfaces
python generate_eigenfaces.py

start eigenfaces_olivetti.html

Detailed step-by-step guide for running the Eigenfaces pipeline on Windows using Git Bash. The script downloads the AT&T Olivetti dataset, runs real sklearn PCA, and generates the self-contained HTML visualization — all from five simple commands.

Pipeline Overview

sklearn runs on your machine, fetches the real AT&T Olivetti dataset, computes PCA, then bakes everything into a self-contained HTML file you open in any browser.

Setup Steps — Git Bash on Windows

Git Bashpython --version
# Python 3.11.x

# If that fails, try:
python3 --version

Git Bash# Change to match where you saved the files:
cd /c/Users/YourName/Downloads/eigenfaces

# Verify all files are there:
ls
generate_eigenfaces.py  eigenfaces_template.html  eigenfaces_sklearn.html

Git Bashpip install scikit-learn numpy pillow

If pip is not foundpython -m pip install scikit-learn numpy pillow

Git Bashpython generate_eigenfaces.py

Expected output[1/5] Fetching Olivetti faces dataset via sklearn...
      X.shape = (400, 4096)
[2/5] Running PCA(n_components=50).fit(X)...
[3/5] Downsampling 64×64 → 32×32...
[4/5] Encoding to base64...
[5/5] Building eigenfaces_olivetti.html...

✓  eigenfaces_olivetti.html  (2100 KB)

Git Bashstart eigenfaces_olivetti.html

Alternative# Double-click the file in Windows Explorer
# Or drag it into Chrome / Firefox

Troubleshooting

Four files make up the project. Keep them all in the same folder — the Python script looks for the template by relative path.

The core challenge is that browsers cannot run Python. The solution is a build-time bridge: Python runs once on your machine, does all the heavy computation, then serializes the results into a self-contained HTML file the browser can display with pure JavaScript.

Why not just run sklearn in the browser?

Browsers execute only JavaScript. Python libraries like sklearn, numpy, and scipy cannot run client-side. Pyodide (Python-in-WebAssembly) could in theory work but would require downloading a 30+ MB runtime and would be far slower.

The chosen approach — pre-compute in Python, embed in HTML — gives the best of both worlds: real sklearn results with zero browser dependencies. The generated HTML is completely self-contained and can be shared, emailed, or opened offline.

Data Flow Detail

Eigenfaces is a classical computer vision technique introduced by Turk and Pentland (1991). It applies Principal Component Analysis (PCA) to a dataset of face images, discovering the directions of greatest variance — the "eigenfaces" — and uses projection into this low-dimensional space for recognition.

The AT&T Olivetti Faces Dataset

Collected at AT&T Laboratories Cambridge between 1992–1994. Contains 400 grayscale photographs of 40 distinct subjects, with 10 images per person. Variations include different lighting conditions, facial expressions (open/closed eyes, smiling/neutral), and accessories (glasses or no glasses). Each image is 64×64 pixels = 4,096 dimensions.

Core Methodology Steps

SVD Decomposition

sklearn PCA centers the data matrix and applies truncated SVD:

Explained Variance Ratio

Each singular value σᵢ corresponds to one eigenface. The fraction of total variance it explains:

Projection (Encoding)

Reconstruction (Decoding)

Recognition Distance

generate_eigenfaces.py runs in five stages. Each stage is clearly printed to the terminal so you can follow progress.

Stage 1 — Fetch the Dataset

sklearn downloads the AT&T Olivetti dataset from figshare.com (~5 MB) and caches it locally in ~/scikit_learn_data/. Future runs use the cache.

      Python · generate_eigenfaces.py · Stage 1
      from sklearn.datasets import fetch_olivetti_faces

dataset = fetch_olivetti_faces(shuffle=False)

X      = dataset.data    # (400, 4096) float32 — flattened images, range [0,1]
y      = dataset.target  # (400,)      int     — identity labels 0..39
images = dataset.images  # (400,64,64) float32 — 2D pixel arrays
    

Stage 2 — Run Real sklearn PCA

PCA.fit(X) centers X by mean, then calls LAPACK's truncated SVD. All results are standard sklearn attributes.

      Python · generate_eigenfaces.py · Stage 2
      from sklearn.decomposition import PCA

K   = 50
pca = PCA(n_components=K, whiten=False)
pca.fit(X)

# Standard sklearn PCA attributes:
eigenfaces = pca.components_              # (50, 4096) — right singular vectors
mean_face  = pca.mean_                    # (4096,)    — mean over training set
evr        = pca.explained_variance_ratio_ # (50,)     — variance per component
singular_v = sqrt(pca.explained_variance_ * (N-1))  # approx σᵢ

# Project all 400 faces into eigenspace:
projections = pca.transform(X)           # (400, 50) — real sklearn output
    

Stage 3 — Downsample for Display

Original images are 64×64 but displayed at 32×32 to keep the HTML file size manageable (~2 MB vs ~8 MB). Pillow's LANCZOS filter gives high quality downsampling.

      Python · generate_eigenfaces.py · Stage 3
      from PIL import Image as PILImage

def resize32(arr_64):
    u8  = (arr_64.clip(0,1) * 255).astype('uint8')
    pil = PILImage.fromarray(u8, mode='L').resize((32,32), PILImage.LANCZOS)
    return array(pil, dtype='float32') / 255.0

faces_32 = stack([resize32(images[i]) for i in range(400)])  # (400,32,32)
mean_32  = resize32(mean_face.reshape(64,64))               # (32,32)
ef_32    = stack([resize32(normalize(eigenfaces[i])) for i in range(K)])  # (50,32,32)
    

Stage 4 — Encode to base64

Float arrays are quantized to uint8 and base64-encoded so they can be embedded as strings inside the HTML/JavaScript. The browser decodes them back with atob().

      Python · generate_eigenfaces.py · Stage 4
      import base64, json

def b64(arr):
    u8 = (arr.clip(0,1) * 255).astype('uint8')
    return base64.b64encode(u8.tobytes()).decode('ascii')

payload = {
    "faces_b64":   b64(faces_32.reshape(400,-1)),     # 400 × 1024 pixels
    "mean_b64":    b64(mean_32.flatten()),            # 1024 pixels
    "ef_b64":      b64(ef_32.reshape(K,-1)),          # 50 × 1024 pixels
    "projections": projections.tolist(),              # (400, 50) full precision
    "evr":         evr.tolist(),                      # (50,)
    "labels":      y.tolist(),                        # (400,) identity IDs
}
    

Stage 5 — Inject into HTML Template

The template contains a single placeholder comment. Python replaces it with the full JSON payload — resulting in a self-contained HTML file.

      Python · generate_eigenfaces.py · Stage 5
      json_str = json.dumps(payload, separators=(',',':'))  # compact JSON

html = open('eigenfaces_template.html').read()

# Replace placeholder with real sklearn data:
html = html.replace(
    '/* __SKLEARN_DATA__ */',
    f'const DATA = {json_str};'
)

open('eigenfaces_olivetti.html', 'w').write(html)
    

The HTML file is pure vanilla JavaScript — no frameworks, no external dependencies. All face rendering uses the HTML5 <canvas> API.

Decoding Embedded Data

When the page loads, the injected DATA constant is decoded back from base64 to pixel arrays.

      JavaScript · eigenfaces_template.html · Data Decoding
      // DATA is injected by Python — the const is already in the HTML
const FW = DATA.img_w, FH = DATA.img_h, FD = FW * FH;  // 32, 32, 1024

function decodeU8B64(b64, rows, cols) {
    const raw = atob(b64);                     // base64 → raw bytes
    const u8  = new Uint8Array(raw.length);
    for (let i = 0; i < raw.length; i++)
        u8[i] = raw.charCodeAt(i);

    const arr = [];
    for (let i = 0; i < rows; i++) {
        const row = new Float32Array(cols);
        for (let j = 0; j < cols; j++)
            row[j] = u8[i*cols + j] / 255;    // uint8 → [0,1]
        arr.push(row);
    }
    return arr;
}

const ALL_FACES   = decodeU8B64(DATA.faces_b64,  400, FD);
const MEAN_FACE   = decodeU8B64(DATA.mean_b64,   1,   FD)[0];
const EIGENFACES  = decodeU8B64(DATA.ef_b64,     50,  FD);
const PROJECTIONS = DATA.projections;  // (400, 50) full float64 from sklearn
    

Drawing a Face on Canvas

Every face image — original, eigenface, reconstructed — uses the same canvas drawing function.

      JavaScript · Face Rendering
      function drawFace(canvas, face, w, h, displayW, displayH) {
    canvas.width = displayW; canvas.height = displayH;
    const ctx = canvas.getContext('2d');

    // Normalize to [0,1] for rendering (handles negative eigenface values)
    let mn = Infinity, mx = -Infinity;
    for (const v of face) { if (v < mn) mn=v; if (v > mx) mx=v; }

    // Write pixel-by-pixel into ImageData at native resolution
    const img = ctx.createImageData(w, h);
    for (let i = 0; i < w*h; i++) {
        const v = Math.round((face[i]-mn)/(mx-mn+1e-8) * 255);
        img.data[i*4]   = v;    // R
        img.data[i*4+1] = v;    // G
        img.data[i*4+2] = v;    // B
        img.data[i*4+3] = 255; // A (fully opaque)
    }
    // Scale up from 32×32 → display size with pixelated rendering
    const tmp = document.createElement('canvas');
    tmp.width=w; tmp.height=h;
    tmp.getContext('2d').putImageData(img, 0, 0);
    ctx.drawImage(tmp, 0, 0, displayW, displayH);
}
    

Reconstruction in JavaScript

The browser re-implements pca.inverse_transform() using the pre-computed projections and eigenfaces from sklearn.

      JavaScript · Face Reconstruction
      function reconstructFace(faceIdx, k) {
    // Start from mean face (equivalent to pca.mean_)
    const recon = new Float32Array(FD);
    for (let j=0; j<FD; j++) recon[j] = MEAN_FACE[j];

    // Add weighted eigenfaces: Σᵢ wᵢ · efᵢ
    for (let ki=0; ki<k; ki++) {
        const w  = PROJECTIONS[faceIdx][ki]; // real sklearn projection weight
        const ef = EIGENFACES[ki];            // real sklearn eigenface
        for (let j=0; j<FD; j++) recon[j] += w * ef[j];
    }
    return recon;
}
    

Nearest-Neighbor Recognition

The recognition step projects the (noisy) query face into eigenspace using the stored eigenfaces, then finds the nearest training projection by Euclidean distance.

      JavaScript · Recognition
      function recognize(queryFace, k) {
    // 1. Center the query face
    const centered = queryFace.map((v, j) => v - MEAN_FACE[j]);

    // 2. Project: w_q = (query - mean) · Vᵏᵀ
    const qProj = EIGENFACES.slice(0, k).map(ef => {
        let d = 0;
        for (let j=0; j<FD; j++) d += centered[j] * ef[j];
        return d;
    });

    // 3. Find nearest training projection by L2 distance
    let minDist = Infinity, bestIdx = 0;
    PROJECTIONS.forEach((p, i) => {
        let d = 0;
        for (let ki=0; ki<k; ki++) d += (p[ki] - qProj[ki]) ** 2;
        if (Math.sqrt(d) < minDist) { minDist = Math.sqrt(d); bestIdx = i; }
    });
    return { match: bestIdx, dist: minDist, identity: LABELS[bestIdx] };
}
    

This project demonstrates a general pattern for bringing any Python ML computation into a static HTML page. The pattern has three parts:

The visualization has a fixed two-column layout: a sidebar on the left for controls and stats, and a main panel on the right with five tabs corresponding to the five stages of the Eigenfaces pipeline.

Layout Regions

Eigenfaces · sklearn PCA · AT&T Olivetti Faces  ·  MSDE Cohort 4  ·  User Guide v1.0