# Contributing to Sampling & Quantization Demo

Thank you for your interest in contributing! This educational tool is designed for teaching image analysis concepts.

## How to Contribute

### Reporting Issues

If you find bugs or have suggestions:
1. Check if the issue already exists in the GitHub Issues
2. Create a new issue with:
   - Clear description of the problem
   - Steps to reproduce (if it's a bug)
   - Expected vs actual behavior
   - Screenshots if applicable

### Suggesting Enhancements

We welcome ideas for educational improvements:
- Additional visualization methods
- New image processing concepts to demonstrate
- Better explanations of existing concepts
- Interactive exercises or quizzes
- Support for additional image formats

### Code Contributions

1. **Fork the repository**

2. **Create a feature branch:**
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **Make your changes:**
   - Follow the existing code style
   - Add comments for complex logic
   - Update documentation if needed

4. **Test your changes:**
   ```bash
   streamlit run app.py
   ```
   - Test all interactive features
   - Verify calculations are correct
   - Check edge cases

5. **Commit your changes:**
   ```bash
   git add .
   git commit -m "Add: Brief description of your changes"
   ```

6. **Push and create a Pull Request:**
   ```bash
   git push origin feature/your-feature-name
   ```
   Then create a PR on GitHub with a clear description.

## Code Style Guidelines

### Python Code

- Follow PEP 8 style guide
- Use meaningful variable names
- Add docstrings to functions:
  ```python
  def function_name(param):
      """
      Brief description.
      
      Args:
          param: Description
      
      Returns:
          Description of return value
      """
  ```

### Streamlit UI

- Keep UI simple and intuitive
- Use consistent markdown formatting
- Add helpful tooltips (help parameter in widgets)
- Organize content in logical sections

### Documentation

- Update README.md for major features
- Keep QUICKSTART.md up to date
- Add inline comments for complex algorithms
- Include references to educational sources

## Educational Content Guidelines

This is an educational tool, so clarity is paramount:

1. **Explanations should be:**
   - Accurate and technically correct
   - Easy to understand for graduate students
   - Progressive (simple concepts first)
   - Include visual examples

2. **Interactive elements should:**
   - Provide immediate feedback
   - Show clear cause-and-effect
   - Include reasonable default values
   - Have helpful tooltips

3. **Calculations should:**
   - Be transparent and explainable
   - Show formulas when relevant
   - Include units
   - Be verifiable

## Testing

Before submitting a PR, please verify:

- [ ] App runs without errors
- [ ] All sliders and controls work correctly
- [ ] File size calculations are accurate
- [ ] Images display properly
- [ ] Compression comparison works
- [ ] Educational content is clear
- [ ] No typos in text

## Questions?

Feel free to open an issue for discussion before starting major work.

## License

By contributing, you agree that your contributions will be licensed under the MIT License.