Skip to main content

Contributing to Reciclaje AI

Thank you for your interest in contributing to Reciclaje AI! This project aims to make recycling more efficient through AI-powered waste detection and classification.
Contributions of all kinds are welcome - from bug fixes and documentation improvements to new features and model enhancements.

Ways to Contribute

Report Bugs

Found a bug? Report it on GitHub Issues with detailed information

Suggest Features

Have an idea? Share it through GitHub Issues or Discussions

Improve Documentation

Help make the docs better for everyone

Write Code

Submit pull requests for bug fixes or new features

Train Models

Help improve detection accuracy with better training data

Share Knowledge

Help others in the community and spread the word

Getting Started

1. Fork and Clone

1

Fork the Repository

Visit the GitHub repository and click the “Fork” button.
2

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/reciclaje_ai.git
cd reciclaje_ai
3

Add Upstream Remote

git remote add upstream https://github.com/AprendeIngenia/reciclaje_ai.git

2. Set Up Development Environment

# Create virtual environment
python -m venv venv

# Activate it
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
# Install required packages
pip install ultralytics opencv-python pillow imutils numpy

# Install development dependencies
pip install pytest black flake8
Download the trained model from Hugging Face:
mkdir -p Modelos
# Place best.pt in Modelos/ directory

3. Create a Branch

Always create a new branch for your changes:
git checkout -b feature/your-feature-name
Use descriptive branch names:
  • feature/add-new-material-detection
  • fix/camera-initialization-error
  • docs/improve-installation-guide

Making Changes

Code Guidelines

  • Follow PEP 8 style guidelines
  • Use meaningful variable and function names
  • Add comments for complex logic
  • Keep functions focused and concise
Format your code:
black *.py
flake8 *.py
Good practices:
  • Extract magic numbers into constants
  • Use configuration files for settings
  • Handle exceptions properly
  • Add docstrings to functions
Example:
# Good
DEFAULT_CAMERA_INDEX = 0
CAMERA_WIDTH = 1280
CAMERA_HEIGHT = 720

def initialize_camera(index=DEFAULT_CAMERA_INDEX):
    """Initialize camera with default settings.
    
    Args:
        index: Camera device index
        
    Returns:
        cv2.VideoCapture object or None if failed
    """
    cap = cv2.VideoCapture(index)
    if not cap.isOpened():
        return None
    cap.set(3, CAMERA_WIDTH)
    cap.set(4, CAMERA_HEIGHT)
    return cap
Write clear, descriptive commit messages:Format:
type: Brief description (50 chars or less)

More detailed explanation if needed.
- Bullet points for multiple changes
- Reference issue numbers: Fixes #123
Types:
  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • refactor: Code refactoring
  • test: Adding tests
  • chore: Maintenance tasks
Examples:
feat: Add support for battery waste detection
fix: Resolve camera initialization on Linux
docs: Update installation instructions for Windows

Testing Your Changes

1

Test Locally

Run the application and verify your changes work:
python TrashDetect.py  # Simple version
python main.py         # GUI version
2

Test Edge Cases

  • Test with different cameras
  • Test with various lighting conditions
  • Test with multiple objects
  • Test error handling
3

Check Performance

Ensure your changes don’t negatively impact:
  • Frame rate
  • Detection accuracy
  • Memory usage

Submitting Changes

Create a Pull Request

1

Commit Your Changes

git add .
git commit -m "feat: Add your feature description"
2

Push to Your Fork

git push origin feature/your-feature-name
3

Open Pull Request

  1. Go to your fork on GitHub
  2. Click “Compare & pull request”
  3. Fill out the PR template
  4. Submit the pull request

Pull Request Guidelines

## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement

## Changes Made
- Detailed list of changes
- Include file names if relevant

## Testing
- How you tested these changes
- Test cases covered

## Screenshots (if applicable)
Add screenshots or videos demonstrating the changes

## Related Issues
Fixes #123, Relates to #456
Checklist:
  • Code follows project style guidelines
  • Code has been tested locally
  • Comments added for complex logic
  • Documentation updated if needed
  • No unnecessary files included
  • Commit messages are clear
  • Branch is up to date with main

Contribution Areas

Improve Detection Model

Model Enhancement

Help improve detection accuracy:
  • Collect and label more training data
  • Test with different lighting conditions
  • Add new waste categories
  • Optimize model performance
  • Create model evaluation scripts

Enhance User Interface

UI/UX Improvements

Make the application more user-friendly:
  • Improve GUI design
  • Add configuration interface
  • Create settings panel
  • Add multi-language support
  • Improve error messages

Add New Features

Feature Ideas

Potential features to implement:
  • Statistics tracking and reporting
  • Database integration for history
  • Web interface or REST API
  • Mobile app version
  • Batch image processing
  • Export detection results
  • Real-time alerts and notifications

Documentation

Documentation Tasks

Help improve documentation:
  • Add more code examples
  • Create video tutorials
  • Translate documentation
  • Write troubleshooting guides
  • Document API endpoints
  • Create architecture diagrams

Support the Project

There are many ways to support Reciclaje AI beyond code contributions!

Subscribe on YouTube

Subscribe to AprendeIngenia’s YouTube channel

Star on GitHub

Give the project a star to show your support

Share the Project

Tell others about Reciclaje AI on social media

Report Issues

Help identify and report bugs or improvements

Community Guidelines

Be respectful, constructive, and welcoming to all contributors.
  • Be respectful: Treat everyone with respect and kindness
  • Be constructive: Provide helpful feedback and suggestions
  • Be patient: Remember that maintainers are volunteers
  • Be collaborative: Work together to solve problems
  • Be positive: Celebrate contributions and successes

Questions?

If you have questions about contributing: Thank you for contributing to Reciclaje AI!

Build docs developers (and LLMs) love