GETTING_STARTED.md

#  Getting Started with the Sampling & Quantization Demo

Welcome! This guide will help you get the demo up and running in just a few minutes.

## Prerequisites

- **Python 3.11+** (Python 3.9+ should also work)
- **Git** (for cloning the repository)
- **pip** (usually comes with Python)
- **5-10 minutes** of your time

Optional:
- **Make** (for convenient commands)
- **Docker** (for containerized deployment)

## ‍️ Quick Start (30 seconds)

The absolute fastest way to get started:

```bash
# 1. Navigate to the project directory (you're probably already here)
cd sampling-quantization

# 2. Run the setup script
./setup.sh

# 3. Run the app
./run_simple.sh
```

That's it! Your browser should open to `http://localhost:8501`

## Detailed Installation

### Step 1: Clone the Repository (if needed)

If you don't have the code yet:

```bash
git clone <repository-url>
cd sampling-quantization
```

### Step 2: Choose Your Setup Method

#### Option A: Automatic Setup (Recommended)

```bash
./setup.sh
```

This will:
- Create a virtual environment
- Install all dependencies
- Verify your Python version
- Run basic checks

#### Option B: Manual Setup

```bash
# Create virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate  # On macOS/Linux
# OR
venv\Scripts\activate  # On Windows

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
```

#### Option C: Using Make

```bash
make setup
```

### Step 3: Run the Application

#### Option A: Quick Run Script

```bash
./run_simple.sh
```

#### Option B: Manual Run

```bash
source venv/bin/activate  # Activate virtual environment
streamlit run app.py
```

#### Option C: Using Make

```bash
make run
```

### Step 4: Open in Browser

The app should automatically open in your default browser at:
```
http://localhost:8501
```

If it doesn't open automatically, manually navigate to that URL.

## Verify Installation

Run the test script to make sure everything is working:

```bash
# Activate virtual environment first
source venv/bin/activate

# Run tests
python test_setup.py
```

You should see:
```
 All tests passed! Ready to run the demo.
```

## First Steps in the Demo

Once the app is running:

1. **Upload an Image** (optional)
   - Look in the sidebar
   - Click "Upload your own image"
   - Or use the default generated image

2. **Try Sampling**
   - Move the "Sampling Grid Size" slider
   - Watch the image become pixelated
   - See the file size decrease

3. **Try Quantization**
   - Move the "Bits per Pixel" slider
   - Notice color banding
   - Observe storage savings

4. **Try Compression**
   - Scroll down to "Compression Methods"
   - Adjust JPEG quality
   - Compare PNG vs JPEG sizes

5. **Explore Educational Content**
   - Click on the three tabs: Sampling, Quantization, Compression
   - Read the explanations
   - Experiment with different settings

## Troubleshooting

### Problem: "Python not found"

**Solution:**
```bash
# Check if Python is installed
python3 --version

# If not, install Python 3.11+ from python.org
```

### Problem: "Permission denied" when running scripts

**Solution:**
```bash
chmod +x *.sh
```

### Problem: Import errors when running

**Solution:**
```bash
# Make sure you're in the virtual environment
source venv/bin/activate

# Reinstall requirements
pip install --force-reinstall -r requirements.txt
```

### Problem: "Port 8501 already in use"

**Solution:**
```bash
# Find and kill the process using the port
lsof -ti:8501 | xargs kill

# Or run on a different port
streamlit run app.py --server.port 8502
```

### Problem: OpenCV import error on macOS

**Solution:**
```bash
# Install system dependencies
brew install opencv

# Or if using apt (Linux)
sudo apt-get install libgl1 libglib2.0-0
```

### Problem: App is slow or unresponsive

**Solution:**
- Reduce image size (images are auto-resized to 512px)
- Close other browser tabs
- Check your internet connection (if loading external images)

## Next Steps

### For Students
- Work through the "Educational Insights" tabs
- Try uploading different types of images
- Calculate storage requirements for your own use cases
- Answer the discussion questions in PROJECT_SUMMARY.md

### For Instructors
- Review QUICKSTART.md for teaching tips
- Customize the app (see CONTRIBUTING.md)
- Deploy to Hugging Face Spaces (see below)
- Share with your class

### For Developers
- Read CONTRIBUTING.md for development guidelines
- Check out PROJECT_SUMMARY.md for technical details
- See IMAGES.md for working with custom images

## Deploying to Hugging Face Spaces

Want to share this with others online?

### Step 1: Create a Hugging Face Account
- Go to https://huggingface.co/join
- Sign up for free

### Step 2: Create a New Space
- Go to https://huggingface.co/new-space
- Choose "Streamlit" as the SDK
- Make it public (for educational use)

### Step 3: Deploy

```bash
./deploy.sh
```

Follow the prompts and enter your Space name (e.g., "username/sampling-demo").

Your demo will be live at: `https://huggingface.co/spaces/username/sampling-demo`

## Docker Deployment (Advanced)

If you prefer Docker:

```bash
# Build the image
docker build -t sampling-demo .

# Run the container
docker run -p 8501:8501 sampling-demo

# Access at http://localhost:8501
```

## Common Commands Reference

```bash
# Setup and installation
./setup.sh              # Initial setup
make setup             # Alternative using make

# Running the app
./run_simple.sh        # Quick run
make run               # Alternative using make
streamlit run app.py   # Direct run

# Testing
python test_setup.py   # Verify installation
make test             # Alternative using make

# Deployment
./deploy.sh            # Deploy to HuggingFace
./check_status.sh      # Check deployment status
make deploy           # Alternative using make

# Cleanup
make clean            # Remove virtual environment
```

## Learning Resources

Before diving in, you might want to review:
- Digital image representation basics
- Sampling theory (Nyquist theorem)
- Quantization and bit depth
- Image compression fundamentals

Good starting points:
- [Digital Image Processing - Wikipedia](https://en.wikipedia.org/wiki/Digital_image_processing)
- [Nyquist-Shannon Sampling Theorem](https://en.wikipedia.org/wiki/Nyquist%E2%80%93Shannon_sampling_theorem)
- [Image Compression - Basics](https://en.wikipedia.org/wiki/Image_compression)

## 🆘 Getting Help

### Documentation
- **README.md** - Project overview
- **QUICKSTART.md** - Quick reference for teaching
- **PROJECT_SUMMARY.md** - Technical details
- **IMAGES.md** - Working with images
- **CONTRIBUTING.md** - Development guide

### Support
- **Issues**: Report bugs on GitHub
- **Discussions**: Ask questions in GitHub Discussions
- **Email**: Contact the course instructor

## Success!

If you made it here and the app is running, congratulations! 

You're ready to explore the fascinating world of image sampling and quantization.

**Enjoy the demo!**