contribution-grid

A Rust crate for generating customizable, GitHub-style contribution heatmap graphs as images.

This crate provides a builder interface to create contribution heatmaps, similar to those found on GitHub user profiles. It supports custom date ranges, colors, and dimensions, outputting the result as an image.

Usage

Add this to your project:

cargo add contribution-grid

Example

use contribution_grid::{ContributionGraph, builtins::Theme, builtins::Strategy};
use chrono::NaiveDate;
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut data = HashMap::new();
    data.insert(NaiveDate::from_ymd_opt(2023, 1, 1).unwrap(), 5);
    data.insert(NaiveDate::from_ymd_opt(2023, 1, 2).unwrap(), 12);

    // Use a built-in theme with a linear mapping strategy
    let img = ContributionGraph::new()
        .with_data(data)
        .theme(Theme::blue(Strategy::linear()))
        .generate();

    img.save("graph.png")?;
    Ok(())
}

Mapping Strategies

The library supports different ways to map contribution counts to colors via the [Strategy] factory:

Strategy::linear(): Maps counts linearly based on the maximum count in the dataset.
Strategy::logarithmic(): Emphasizes differences at lower values.
Strategy::threshold(vec![...]): Uses fixed user-defined thresholds.

You can also use the strategy structs directly:

LinearStrategy: Linear percentile-based mapping.
LogarithmicStrategy: Logarithmic mapping.
ThresholdStrategy::new(vec![...]): Fixed threshold mapping.

use contribution_grid::builtins::{Theme, Strategy};

// Use the factory (recommended)
let palette = Theme::github(Strategy::linear());

// Or use structs directly
use contribution_grid::ThresholdStrategy;
let palette = Theme::github(ThresholdStrategy::new(vec![1, 5, 10, 20]));