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