Spaces:

ubern-introimage
/

sampling-quantization

Sleeping

# 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:

git clone <repository-url>
cd sampling-quantization

Step 2: Choose Your Setup Method

Option A: Automatic Setup (Recommended)

./setup.sh

This will:

Create a virtual environment
Install all dependencies
Verify your Python version
Run basic checks

Option B: Manual Setup

# 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

make setup

Step 3: Run the Application

Option A: Quick Run Script

./run_simple.sh

Option B: Manual Run

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

Option C: Using Make

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:

# 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:

Upload an Image (optional)
- Look in the sidebar
- Click "Upload your own image"
- Or use the default generated image
Try Sampling
- Move the "Sampling Grid Size" slider
- Watch the image become pixelated
- See the file size decrease
Try Quantization
- Move the "Bits per Pixel" slider
- Notice color banding
- Observe storage savings
Try Compression
- Scroll down to "Compression Methods"
- Adjust JPEG quality
- Compare PNG vs JPEG sizes
Explore Educational Content
- Click on the three tabs: Sampling, Quantization, Compression
- Read the explanations
- Experiment with different settings

Troubleshooting

Problem: "Python not found"

Solution:

# Check if Python is installed
python3 --version

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

Problem: "Permission denied" when running scripts

Solution:

chmod +x *.sh

Problem: Import errors when running

Solution:

# 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:

# 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:

# 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

./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:

# 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

# 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:

🆘 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!