CONTRIBUTING.md

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:

   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:

   streamlit run app.py
   

   • Test all interactive features
   • Verify calculations are correct
   • Check edge cases

5. Commit your changes:

   git add .
   git commit -m "Add: Brief description of your changes"
   

6. Push and create a Pull Request:

   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:

  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.