CONTRIBUTING.md

Contributing to Colorimetry

Table of contents

• Reporting bugs
• Suggesting features
• Setup
• Adding a color space
• Adding a grayscale method
• Pull requests
• Further reading

Reporting bugs

Open an issue with:

• Java version and OS
• Code snippet that reproduces the problem
• Expected vs actual result
• If it's a color accuracy issue, include the input values, target space, and what the correct output should be (with source/reference)

Suggesting features

Open an issue describing the use case before writing code. For new color spaces, include a link to the reference paper or specification.

Setup

git clone https://github.com/PedroFellipeAntunes/Colorimetry-java.git
cd Colorimetry-java
mvn compile

Requires Java 11+.

Adding a color space

1. Create a class in the appropriate subpackage under colorimetry/spaces/ (e.g. spaces/hue/, spaces/perceptual/, spaces/cam/). Implement ColorSpace.
2. Add a public static final INSTANCE singleton as the first field.
3. Implement metadata: displayName, componentCount, componentName, componentMin, componentMax, componentDefault, componentStep.
4. Declare parentSpace() - pick the closest existing space in the hierarchy.
5. Implement toParent() and fromParent() with the conversion math.
6. Implement normalize() and denormalize() for the 0-1 range mapping.
7. Root spaces (parent = Xyz) must also override isBounded(). Child spaces inherit this from their root ancestor.
8. For cylindrical spaces, override isCylindrical() (return true), hueChannel(), and radialChannel().
9. For spaces where only some channels are bounded, override isChannelBounded(int i).
10. For spaces with a configurable parent, implement a static of(parent) factory and override acceptedParentType() returning the appropriate marker interface (RgbLike.class, XyzLike.class, or LabLike.class).
11. Register in ColorSpaceRegistry static block.
12. Run ColorSpaceAtlasTest, ColorSpaceTreeTest, ColorSpaceGamutExport, and RoundTripTest to verify. See Testing for details on each test and its arguments.

Adding a grayscale method

1. Create a class in the appropriate subpackage under colorimetry/grayscale/ (e.g. grayscale/luma/, grayscale/perceptual/, grayscale/simple/, grayscale/channel/). Implement Grayscale.
2. Add a public static final INSTANCE singleton.
3. Implement nativeSpace() - return the color space where the method operates (e.g. CieLab.INSTANCE, Oklab.INSTANCE, SRgb.INSTANCE).
4. Implement toGrayNative() - receives raw values in the native space, returns achromatic values in the same space (e.g. zero chromatic channels). The default toGray in the interface handles conversion to/from the native space automatically.
5. For luma-weighted methods, use the shared Grayscale.applyLuma(raw, luma) utility with coefficients from RgbLike.lumaCoefficients().
6. Register in GrayscaleRegistry static block.
7. Run GrayscaleGradientTest and GrayscaleAtlasTest to verify the result visually. See Testing for details.

Pull requests

• One feature per PR.
• Branch from main.
• Follow the code style.
• Run the relevant tests for what you changed (see Adding a color space or Adding a grayscale method) and check the output before submitting.
• Describe what was changed and why in the PR description.

Further reading

• Code style - formatting rules, section headers, and comment conventions.
• Architecture - conversion pipeline, gamut mapping, and internal design.
• Testing - all test programs, what they do, and how to run them.