contribution-grid 2.0.0

A Rust crate for generating customizable, GitHub-style contribution heatmap graphs as images
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# contribution-grid

[![Crates.io](https://img.shields.io/crates/v/contribution-grid.svg)](https://crates.io/crates/contribution-grid)
[![Documentation](https://docs.rs/contribution-grid/badge.svg)](https://docs.rs/contribution-grid)
[![License](https://img.shields.io/crates/l/contribution-grid.svg)](LICENSE)

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:

```bash
cargo add contribution-grid
```

## Example

```rust
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.

```rust
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]));
```

## Themes

The library comes with several built-in themes:

### GitHub (Default)
![GitHub Theme](docs/github_theme_random.png)

### GitHub Old
![GitHub Old Theme](docs/github_old_theme_heavy.png)

### Blue
![Blue Theme](docs/blue_theme_weekend.png)

### Red
![Red Theme](docs/red_theme_sparse.png)

### Custom Examples

**Custom Dimensions (Small Boxes):**
![Small Boxes](docs/custom_small_boxes.png)

You can also customize dimensions and colors via the `Palette` struct.

**Custom Neon Theme:**
![Custom Neon](docs/custom_neon_theme.png)

## License

This project is licensed under the [MIT License](LICENSE).