gr

# GR.cr

[![Join the chat at https://gitter.im/crystal-data/bottle](https://badges.gitter.im/crystal-data/bottle.svg)](https://gitter.im/crystal-data/bottle?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![.github/workflows/ci.yml](https://github.com/crystal-data/GR.cr/actions/workflows/ci.yml/badge.svg)](https://github.com/crystal-data/GR.cr/actions/workflows/ci.yml)
[![Lines of Code](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fcrystal-data%2FGR.cr%2Flines)](https://tokei.kojix2.net/github/crystal-data/GR.cr)

<a href="https://github.com/red-data-tools/GR.rb"><img alt="GR.rb" src="https://user-images.githubusercontent.com/5798442/124949370-76312280-e04c-11eb-8e1e-e3a092284584.png" width="366" height="300" align="right"></a>

[Crystal](https://github.com/crystal-lang/crystal) bindings to [GR framework](https://github.com/sciapp/gr).

GR.cr has been forked from [gr-crystal](https://github.com/jmakino/gr-crystal) by [Jun Makino](https://github.com/jmakino).

## Installation

### GR Installation

#### [Official release](https://github.com/sciapp/gr/releases) - Linux, Mac, Windows

Set `GRDIR` : `export GRDIR="your/path/to/gr"`

#### [OpenSUSE build service](https://software.opensuse.org//download.html?project=science%3Agr-framework&package=gr) - Linux

Set `GRDIR` : `export GRDIR="/usr/gr"`

#### [Homebrew](https://formulae.brew.sh/formula/libgr) - Mac

`brew install libgr`

### GR.cr installation

Add the dependency to your `shard.yml`:

```yaml
dependencies:
  gr:
    github: crystal-data/GR.cr
```

Run `shards install`

## API Overview

- `libGR`, `libGR3`, `libGRM` : call native functions directly.
- `GR`, `GR3`, `GRM` : call module function customized for Crystal.

```
  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
  │     GRM      │  │      GR      │  │      GR3     │
  │ ┌──────────┐ │  │ ┌──────────┐ │  │ ┌──────────┐ │
  │ │  LibGRM  │ │  │ │  LibGR   │ │  │ │  LibGR3  │ │
  │ └──────────┘ │  │ └──────────┘ │  │ └──────────┘ │
  └──────────────┘  └──────────────┘  └──────────────┘
```

GR.cr is still immature, but even in its current state, GRM can be used to create good quality figures.

## Quick Start

### Simple Line Plot

```crystal
require "grm"

x = [1.0, 2.0, 3.0, 4.0, 5.0]
y = [1.0, 4.0, 9.0, 16.0, 25.0]

# High-level API
GRM.plot(x, y, title: "My Plot")

# Object-oriented API
plot = GRM::Plot.new
  .data(x, y)
  .color("red")
  .title("My Plot")
  .xlabel("X")
  .ylabel("Y")

plot.show
plot.save("output.png")
```

### Plot Types

```crystal
require "grm"

x = [1, 2, 3, 4, 5]
y = [2, 4, 6, 8, 10]

GRM.plot(x, y, title: "Line Plot")
GRM.scatter(x, y, title: "Scatter Plot")
GRM.barplot(x, y, title: "Bar Chart")
GRM.histogram([1, 2, 2, 3, 3, 3, 4, 4, 5], title: "Histogram")
```

### 3D Surface Plot

```crystal
require "grm"

x = [1.0, 2.0, 3.0]
y = [1.0, 2.0, 3.0]
z = [
  [1.0, 4.0, 9.0],
  [2.0, 8.0, 18.0],
  [3.0, 12.0, 27.0]
]

plot = GRM::Plot.new
  .data2d(x, y, z)
  .surface
  .title("3D Surface")

plot.show
```

### Supported Features

- 2D Plots: line, scatter, barplot, histogram, stem, stairs, hexbin, polar
- 3D Plots: plot3, surface, contour, scatter3
- Output: PNG, HTML, JSON export
- API: High-level functions and object-oriented interface

Note: Multiple 2D plots in one figure do not currently work.

## Usage

Please see the example directory.

With GR and GR3 modules, you can do more serious visualization.
However, you may find that GR.cr is not fully implemented.
In that case, please send me a pull request.

## Development

Low-level bindings are automatically generated by [crystal_lib](https://github.com/crystal-lang/crystal_lib).

GR.cr is a library under development, so even small improvements like fixing typos are welcome! Please feel free to send us your PR.
The author is not familiar with Crystal, so it may be written in an inefficient way, and you may be able to fix it.

- Look at [GR.rb](https://github.com/red-data-tools/GR.rb) and implement the missing methods!
- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features

## Acknowledgements

We would like to thank Josef Heinen, the creator of [GR](https://github.com/sciapp/gr) and [GR.jl](https://github.com/jheinen/GR.jl), Florian Rhiem, the creator of [python-gr](https://github.com/sciapp/python-gr), and all [GR](https://github.com/sciapp/gr) developers.