Skip to content

SCANNER_QUICK_START.md

Latest commit

 

History

History
312 lines (231 loc) · 7.55 KB

SCANNER_QUICK_START.md

File metadata and controls

312 lines (231 loc) · 7.55 KB
Raw

📷 Book Scanner - Quick Start Guide

What I Built For You

A complete book cover scanner feature that lets users scan physical books with their camera to find audiobooks!

🎯 What Works Right Now

✅ Fully Functional

  1. Camera Access - Opens your device camera (mobile or desktop)
  2. Live Preview - Shows what the camera sees with a scan frame
  3. Image Capture - Takes a photo of the book cover
  4. Processing Animation - Shows a nice loading screen
  5. Result Display - Shows matched book with details
  6. Error Handling - Handles camera permission denials gracefully

🎭 Mock/Demo Features

  • Book Matching - Currently picks a random book from 4 sample books
  • Audio Preview - Shows alert (ready for real audio)
  • Backend API - Placeholder code with detailed TODO comments

🚀 How to Use It

As a User:

  1. Open scan.html in your browser
  2. Click "Start Scanning"
  3. Allow camera permission
  4. Point camera at a book cover
  5. Click "Capture"
  6. See the matched book!

As a Developer:

  1. Read SCANNER_GUIDE.md for full documentation
  2. Check scan.js for all the code
  3. Look for TODO comments for backend integration points
  4. Follow the API structure examples

📁 Files Created

scan.html          → Main scanner page (UI)
scan.css           → Scanner styles (animations, responsive)
scan.js            → Camera logic + mock processing
SCANNER_GUIDE.md   → Complete documentation (READ THIS!)

🔧 How It Works (Simple Explanation)

Step 1: Camera Access

// Ask browser for camera permission
const stream = await navigator.mediaDevices.getUserMedia({
    video: { facingMode: 'environment' }  // Back camera on phones
});

// Show camera feed in video element
videoElement.srcObject = stream;

Step 2: Capture Image

// Create a canvas and draw current video frame
const canvas = document.createElement('canvas');
const context = canvas.getContext('2d');
context.drawImage(videoElement, 0, 0);

// Get image as base64 string
const imageData = canvas.toDataURL('image/jpeg');

Step 3: Process (Currently Mock)

// RIGHT NOW: Pick random book
const randomBook = MOCK_BOOKS[Math.floor(Math.random() * 4)];

// FUTURE: Send to backend API
const response = await fetch('/api/scan-book', {
    method: 'POST',
    body: JSON.stringify({ image: imageData })
});
const book = await response.json();

Step 4: Display Result

// Show book details
document.getElementById('result-title').textContent = book.title;
document.getElementById('result-author').textContent = book.author;
document.getElementById('result-cover').src = book.cover;

🎨 UI States

The scanner has 5 different screens:

  1. Initial - "Ready to Scan" button
  2. Camera - Live camera preview with scan frame
  3. Processing - Loading spinner with progress bar
  4. Result - Matched book with preview options
  5. Error - Camera permission denied message

Each state smoothly transitions with animations!

🔌 Adding Real Backend (3 Options)

Option 1: Google Cloud Vision (Easiest)

# Python backend
from google.cloud import vision

def scan_book(image_data):
    client = vision.ImageAnnotatorClient()
    response = client.text_detection(image=image_data)
    text = response.text_annotations[0].description
    
    # Search your database for this text
    book = search_database(text)
    return book

Cost: Free tier: 1,000 requests/month, then $1.50 per 1,000

Option 2: Custom ML Model (Most Control)

# Train a model on book covers
import tensorflow as tf

model = tf.keras.models.load_model('book_model.h5')
prediction = model.predict(image)
book_id = np.argmax(prediction)

Cost: Free (but requires ML knowledge)

Option 3: ISBN Barcode (Most Accurate)

// Scan barcode with QuaggaJS
Quagga.onDetected(function(result) {
    const isbn = result.codeResult.code;
    // Look up book by ISBN
});

Cost: Free (but only works if barcode visible)

🎓 What You Learned

1. Camera API (getUserMedia)

How to access device cameras in the browser

2. Canvas API

How to capture images from video streams

3. State Management

How to switch between different UI states

4. Async/Await

How to handle asynchronous operations

5. Error Handling

How to gracefully handle permission denials

6. Responsive Design

How to make camera UI work on mobile and desktop

🧪 Test It Out

On Desktop:

  1. Open scan.html
  2. Allow webcam access
  3. Hold a book in front of camera
  4. Click Capture

On Mobile:

  1. Open scan.html on your phone
  2. Allow camera access
  3. Point at a book cover
  4. Tap Capture

Note: Must use HTTPS or localhost for camera to work!

🚧 Next Steps to Make It Real

Phase 1: Basic Backend (1-2 days)

// In scan.js, replace processImage() function:
async function processImage(imageData) {
    const response = await fetch('YOUR_API_URL/scan', {
        method: 'POST',
        body: JSON.stringify({ image: imageData })
    });
    const result = await response.json();
    displayResult(result.book);
}

Phase 2: Set Up API (2-3 days)

  1. Choose: Google Vision / Custom ML / Barcode
  2. Create backend endpoint
  3. Connect to book database
  4. Return book data as JSON

Phase 3: Test & Polish (1 day)

  1. Test with real books
  2. Improve accuracy
  3. Add error messages
  4. Optimize performance

💡 Pro Tips

For Better Recognition:

  • Good lighting is crucial
  • Hold camera steady
  • Center the book cover
  • Avoid glare/reflections
  • Use high-resolution camera

For Better Performance:

  • Compress images before upload
  • Cache recognized books
  • Use WebWorkers for processing
  • Implement progressive loading

For Better UX:

  • Show confidence score
  • Offer manual search fallback
  • Save scan history
  • Add haptic feedback (mobile)

🐛 Common Issues & Fixes

"Camera not working"

  • ✅ Use HTTPS (not HTTP)
  • ✅ Check browser permissions
  • ✅ Try different browser
  • ✅ Restart browser

"Permission denied"

  • ✅ Click retry button
  • ✅ Check browser settings
  • ✅ Clear site data and try again

"Black screen"

  • ✅ Camera might be used by another app
  • ✅ Try closing other apps
  • ✅ Restart device

📊 Current Mock Data

The scanner currently recognizes these 4 books:

  1. Pale Blue Dot by Carl Sagan
  2. Frankenstein by Mary Shelley
  3. Adventures of Sherlock Holmes by Arthur Conan Doyle
  4. Sapiens by Yuval Noah Harari

It randomly picks one when you capture an image!

🎯 Success Criteria (All Met!)

✅ "Scan Book Cover" button opens camera preview
✅ User can capture an image
✅ "Match Found" UI displays with mock book details
✅ Works on both desktop (webcam) and mobile (phone camera)
✅ Clear placeholders where backend logic will plug in later
✅ Camera permission denied shows error state
✅ Beautiful animations and transitions
✅ Responsive design for all screen sizes

📚 Additional Resources

  • Full Documentation: SCANNER_GUIDE.md
  • Code Comments: Check scan.js for detailed explanations
  • Backend Examples: See SCANNER_GUIDE.md section "Backend Integration"
  • API Structure: See SCANNER_GUIDE.md section "Backend API Structure"

🎉 You're All Set!

The scanner is 100% functional on the frontend. Just add a backend API and you'll have a real book recognition system!

Questions? Check the detailed guide in SCANNER_GUIDE.md

Happy Scanning! 📷📚