Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
410 lines (300 loc) · 9.85 KB

CONTRIBUTING.md

File metadata and controls

410 lines (300 loc) · 9.85 KB

Contributing to Eric's Image Processing Nodes

Thank you for your interest in contributing to this project! This document provides guidelines for contributing code, documentation, and other improvements.

Table of Contents

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors, regardless of experience level, gender identity, sexual orientation, disability, personal appearance, race, ethnicity, age, religion, or nationality.

Expected Behavior

  • Be respectful and constructive in discussions
  • Provide helpful feedback
  • Focus on the code and ideas, not the person
  • Be patient with newcomers
  • Give credit where it's due

Unacceptable Behavior

  • Harassment, discrimination, or offensive comments
  • Trolling or deliberately inflammatory behavior
  • Publishing others' private information without permission
  • Any conduct that would be considered inappropriate in a professional setting

How Can I Contribute?

Reporting Bugs

Before submitting a bug report:

  1. Check the existing GitHub Issues
  2. Test with the latest version
  3. Ensure it's not a ComfyUI issue (try with vanilla ComfyUI)

When submitting a bug report, include:

  • ComfyUI version
  • Python version
  • Operating system
  • GPU/CUDA version (if using GPU features)
  • Complete error message and traceback
  • Minimal reproducible example
  • Screenshots or workflow JSON if applicable

Suggesting Enhancements

We welcome suggestions for new features! Please include:

  • Clear description of the feature
  • Use case and motivation
  • Example of how it would work
  • Any relevant research papers or algorithms
  • Whether you're willing to implement it yourself

Contributing Code

We welcome contributions of:

  • New Nodes: Additional image processing algorithms
  • Bug Fixes: Corrections to existing code
  • Performance Improvements: Optimizations
  • Documentation: Improvements to guides and examples
  • Tests: Unit tests and integration tests
  • Examples: Sample workflows and use cases

Development Setup

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork:
git clone https://github.com/YOUR_USERNAME/Eric_Image_Processing_Nodes.git
cd Eric_Image_Processing_Nodes

2. Set Up Development Environment

# Create a virtual environment
python -m venv .venv

# Activate it
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install development dependencies
pip install pytest black flake8 mypy

3. Install Pre-commit Hooks (Optional but Recommended)

pip install pre-commit
pre-commit install

4. Link to ComfyUI

# Create a symlink in ComfyUI's custom_nodes directory
# Windows (run as administrator):
mklink /D "C:\path\to\ComfyUI\custom_nodes\Eric_Image_Processing_Nodes" "C:\path\to\your\clone"

# Linux/Mac:
ln -s /path/to/your/clone /path/to/ComfyUI/custom_nodes/Eric_Image_Processing_Nodes

Code Style Guidelines

Python Style

We follow PEP 8 with some modifications:

# Line length: 100 characters (not 79)
# Use 4 spaces for indentation (no tabs)
# Use double quotes for strings (unless single quotes avoid escaping)

File Header Template

All new node files must include a proper header:

"""
[Node Name] for ComfyUI
[Brief description]

Author: Eric Hiss (GitHub: EricRollei)
License: See LICENSE file in repository root

[If using external algorithm/model:]
Original Algorithm:
    Paper: [Title]
    Authors: [Authors]
    Source: [URL]
    License: [License]
    
    Citation:
    @[type]{[key],
      title={[Title]},
      author={[Authors]},
      year={[Year]}
    }

Dependencies:
    - Library (License)
    - Library (License)
"""

Node Structure

Follow the established pattern:

class YourNode(BaseImageProcessingNode):
    """
    Detailed docstring explaining:
    - What the node does
    - When to use it
    - Key parameters
    - Typical use cases
    """
    
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "image": ("IMAGE",),
                # ... other inputs
            }
        }
    
    RETURN_TYPES = ("IMAGE",)
    RETURN_NAMES = ("processed_image",)
    FUNCTION = "process"
    CATEGORY = "Eric's Image Processing/Your Category"
    
    def process(self, image, **kwargs):
        # Process logic here
        pass

Processing Script Structure

Keep processing logic separate from node code:

# scripts/your_algorithm.py
"""
Pure processing functions (no ComfyUI dependencies)
Can be tested standalone
"""

def your_algorithm(image_np: np.ndarray, **params) -> np.ndarray:
    """
    Process image with your algorithm.
    
    Args:
        image_np: Input image as numpy array [H, W, C] with values 0-255
        **params: Algorithm parameters
        
    Returns:
        Processed image as numpy array [H, W, C] with values 0-255
    """
    # Ensure contiguous array for OpenCV compatibility
    image_np = np.ascontiguousarray(image_np)
    
    # Your processing logic
    
    # Ensure output is contiguous
    result = np.ascontiguousarray(result)
    return result

Testing

Add tests for new functionality:

# tests/test_your_node.py
import pytest
import numpy as np
from scripts.your_algorithm import your_algorithm

def test_your_algorithm_basic():
    """Test basic functionality"""
    image = np.random.randint(0, 255, (100, 100, 3), dtype=np.uint8)
    result = your_algorithm(image)
    assert result.shape == image.shape
    assert result.dtype == np.uint8

def test_your_algorithm_edge_cases():
    """Test edge cases"""
    # Test with all black
    black = np.zeros((100, 100, 3), dtype=np.uint8)
    result = your_algorithm(black)
    assert result is not None

License Agreement

By Contributing, You Agree That:

  1. Your contributions will be licensed under the same dual license as the project:

  2. You have the right to contribute the code (it's your original work or you have permission)

  3. You will provide proper attribution for any:

    • External algorithms or models used
    • Research papers implemented
    • Third-party code adapted
    • Dependencies added

  4. You grant the project maintainer (Eric Hiss) the right to:

    • Include your contribution in the project
    • Modify your contribution as needed
    • Relicense your contribution if the project license changes

For Significant Contributions

For major contributions (new models, significant features), please:

  1. Add your name to the CONTRIBUTORS list
  2. Include your email for attribution (optional)
  3. Document your contribution in the commit message

Pull Request Process

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

2. Make Your Changes

  • Follow the code style guidelines
  • Add proper headers to new files
  • Update documentation as needed
  • Add tests for new functionality
  • Ensure all tests pass

3. Commit Your Changes

Use clear, descriptive commit messages:

git commit -m "Add [Feature]: Brief description

- Detailed point 1
- Detailed point 2
- References #issue-number if applicable"

4. Push to Your Fork

git push origin feature/your-feature-name

5. Submit Pull Request

On GitHub:

  1. Go to your fork
  2. Click "New Pull Request"
  3. Select your branch
  4. Fill out the PR template:
    • Description of changes
    • Motivation and context
    • Testing performed
    • Screenshots if UI changes
    • Checklist items completed

6. Code Review

  • Respond to review comments
  • Make requested changes
  • Update the PR
  • Be patient and respectful

7. Merge

Once approved, the maintainer will merge your PR. Thank you! 🎉

Attribution Requirements

When Adding External Algorithms

You must include:

  1. Original paper citation in docstring
  2. Source repository link if applicable
  3. License information of the original work
  4. Author credits
  5. Link to pretrained weights if used

When Adding Dependencies

Update these files:

  1. requirements.txt - Add the dependency
  2. LICENSE - Add dependency license info
  3. Docs/MODEL_WEIGHTS.md - If models are involved
  4. File header - List new dependencies

Example Attribution

"""
Original Algorithm:
    Paper: "Algorithm Name"
    Authors: Smith et al., Conference 2023
    Source: https://github.com/author/repo
    License: MIT License
    Pretrained weights: https://github.com/author/repo/releases
    
    Citation:
    @inproceedings{smith2023algorithm,
      title={Algorithm Name},
      author={Smith, John and Doe, Jane},
      booktitle={Conference},
      year={2023}
    }
    
Implementation Notes:
    [Your modifications or adaptations]
    
Contributed by: [Your Name] (GitHub: @yourusername)
Date: [Month Year]
"""

Questions?

Recognition

Contributors will be acknowledged in:

  • The CONTRIBUTORS file
  • Release notes
  • Documentation credits section

Thank you for contributing! Your work helps the ComfyUI community! 🚀