Spaces:

ubern-introimage
/

sampling-quantization

Sleeping

sampling-quantization / GETTING_STARTED.md

AKA Math

Remove emojis and symbols from all files, update Dockerfile

d962d48 12 months ago

7 kB

#  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!** 

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