Contributing to MarkDiffusion

We welcome contributions from the community! This guide will help you get started.

Note

Please read our Code of Conduct and the detailed Contributing Guidelines in the repository root before contributing.

Overview

This document provides technical guidelines for contributing to MarkDiffusion. For general contribution workflow (forking, cloning, creating branches, submitting PRs), please refer to the Contributing Guidelines in the repository root.

Development Guidelines

Code Style

We follow PEP 8 style guidelines. Please ensure your code:

  • Uses 4 spaces for indentation

  • Has descriptive variable and function names

  • Includes docstrings for all public functions and classes

  • Stays under 100 characters per line when practical

Example:

def generate_watermarked_media(self, input_data, **kwargs):
    """
    Generate watermarked media from input.

    Args:
        input_data (str): Text prompt or input data
        **kwargs: Additional generation parameters

    Returns:
        PIL.Image: Watermarked image

    Examples:
        >>> watermark = AutoWatermark.load('GS', 'markdiffusion/config/GS.json', config)
        >>> image = watermark.generate_watermarked_media("A sunset")
    """
    # Implementation
    pass

Documentation

All new features should include:

  • Docstrings following Google or NumPy style

  • Type hints for function arguments and returns

  • Usage examples in docstrings

  • Updates to relevant documentation pages

Example with type hints:

from typing import Union, Dict, Any
from PIL import Image

def detect_watermark_in_media(
    self,
    media: Union[Image.Image, list],
    **kwargs: Any
) -> Dict[str, Any]:
    """
    Detect watermark in media.

    Args:
        media: PIL Image or list of PIL Images (for video)
        **kwargs: Additional detection parameters

    Returns:
        Dictionary containing detection results with keys:
            - detected (bool): Whether watermark was detected
            - score (float): Detection confidence score
            - threshold (float): Detection threshold used
    """
    pass

Testing

All new code should include comprehensive tests. We use pytest for testing.

Note

For detailed testing instructions, including test structure, markers, and running options, please refer to the test/README.md file in the repository.

For test code examples, please refer to the existing test files in the test/ directory:

  • test/test_watermark_algorithms.py - Watermark algorithm tests

  • test/test_pipelines.py - Pipeline tests

  • test/test_image_editor.py - Image editing tests

  • test/test_video_editor.py - Video editing tests

  • test/test_utils.py - Utility function tests

  • test/test_dataset.py - Dataset tests

Run tests:

# Install test dependencies
pip install -r test/requirements-test.txt

# Run all tests with coverage and HTML report
pytest test -v --cov=. --cov-report=html --cov-report=term-missing --html=report.html

# Test all algorithms
pytest test/test_watermark_algorithms.py -v

# Test a specific algorithm
pytest test/test_watermark_algorithms.py -v --algorithm TR

# Test all pipelines
pytest test/test_pipelines.py -v

For more test commands and options, see test/README.md.

Contribution Process

Adding a New Algorithm

To add a new watermarking algorithm:

  1. Create algorithm directory structure

    watermark/my_algorithm/
├── __init__.py
├── my_algorithm.py
detection/my_algorithm/
├── __init__.py
├── my_algorithm_detection.py
visualize/my_algorithm/
├── __init__.py
├── my_algorithm_visualizer.py
config/
├── MyAlgorithm.json
test/
├── test_my_algorithm.py

  2. Implement the algorithm

    Implement the watermark generation and detection logic.

  3. Add configuration

    Create config/MyAlgorithm.json with algorithm parameters.

  4. Register algorithm

    Add to watermark/auto_watermark.py:

    from markdiffusion.watermark.my_algorithm.my_algorithm import MyAlgorithm

class AutoWatermark:
    ALGORITHM_MAP = {
        # ... existing algorithms
        'MA': MyAlgorithm,
    }

  5. Write tests

    Create comprehensive tests in test/test_my_algorithm.py.

  6. Update documentation

    • Add algorithm description to docs/user_guide/algorithms.rst

    • Update docs/index.rst to list the new algorithm

    • Add usage examples

  7. Submit pull request

    See Pull Request Guidelines below.

Adding Evaluation Tools

To add a new evaluation tool:

  1. Implement the tool

    For image attacks:

    from markdiffusion.evaluation.tools.image_editor import BaseImageEditor

class MyAttack(BaseImageEditor):
    def __init__(self, param1, param2, **kwargs):
        super().__init__(**kwargs)
        self.param1 = param1
        self.param2 = param2

    def edit_image(self, image):
        # Implement attack
        return modified_image

    For quality metrics:

    from markdiffusion.evaluation.tools.image_quality_analyzer import BaseImageQualityAnalyzer

class MyMetric(BaseImageQualityAnalyzer):
    def analyze(self, image1, image2=None):
        # Implement metric
        return score

  2. Add tests

  3. Update documentation

  4. Submit pull request

Submission Checklist

Before submitting your contribution, please ensure you have completed the following:

Type of Change

Please indicate the type of your contribution:

  • 🐛 Bug fix (non-breaking change which fixes an issue)

  • ✨ New feature (non-breaking change which adds functionality)

  • 📝 Documentation update (changes to documentation only)

  • 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)

  • 🔧 Refactor/Optimization (code improvement without changing logic)

Pre-Submission Checklist

  • [ ] I have read and followed the Contributing Guidelines

  • [ ] I have performed a self-review of my own code

  • [ ] My code follows the project’s coding style/standards (PEP 8)

  • [ ] I have added/updated necessary comments and documentation

  • [ ] I have added corresponding test cases (if new feature or bug fix)

  • [ ] All local tests pass successfully

Testing

# Install test dependencies
pip install -r test/requirements-test.txt

# Run all tests with coverage
pytest test -v --cov=. --cov-report=html --cov-report=term-missing --html=report.html

For detailed testing instructions, see test/README.md.

Code Style

# Check code style
flake8 watermark/ detection/ evaluation/ visualize/
black --check watermark/ detection/ evaluation/ visualize/

# Auto-format code
black watermark/ detection/ evaluation/ visualize/

Documentation

  • Update relevant documentation files

  • Add usage examples where appropriate

  • Ensure all docstrings are complete and follow the project style

Pull Request

For the complete pull request process and guidelines, please refer to the Contributing Guidelines in the repository root.

Additional Information

Community Guidelines

All participants are expected to follow our Code of Conduct. Please be respectful, constructive, and help create a welcoming environment for everyone.

Reporting Issues

For bug reports and feature requests, please use the appropriate templates configured in the GitHub repository.

Questions?

If you have questions:

Contact

For major contributions or collaborations:

Thank you for contributing to MarkDiffusion!