go-chart/README.md

100 lines
3.6 KiB
Markdown
Raw Normal View History

2016-07-08 05:37:57 +02:00
go-chart
========
2018-10-05 08:57:51 +02:00
[![Build Status](https://travis-ci.org/wcharczuk/go-chart.svg?branch=master)](https://travis-ci.org/wcharczuk/go-chart) [![Go Report Card](https://goreportcard.com/badge/github.com/wcharczuk/go-chart)](https://goreportcard.com/report/github.com/wcharczuk/go-chart)
2016-07-08 05:37:57 +02:00
Package `chart` is a very simple golang native charting library that supports timeseries and continuous
line charts.
2016-07-15 05:52:05 +02:00
The v1.0 release has been tagged so things should be more or less stable, if something changes please log an issue.
2016-07-12 03:48:51 +02:00
2016-08-07 20:05:57 +02:00
Master should now be on the v2.x codebase, which brings a couple new features and better handling of basics like axes labeling etc. Per usual, see `_examples` for more information.
2016-07-08 05:37:57 +02:00
# Installation
To install `chart` run the following:
```bash
> go get -u github.com/wcharczuk/go-chart
```
Most of the components are interchangeable so feel free to crib whatever you want.
2016-07-17 06:21:50 +02:00
# Output Examples
2016-07-08 05:37:57 +02:00
2016-07-17 05:53:46 +02:00
Spark Lines:
2016-07-08 05:37:57 +02:00
2016-08-07 07:00:22 +02:00
![](https://raw.githubusercontent.com/wcharczuk/go-chart/master/_images/tvix_ltm.png)
2016-07-08 05:37:57 +02:00
2016-07-17 05:53:46 +02:00
Single axis:
2016-07-08 05:37:57 +02:00
2016-08-07 07:00:22 +02:00
![](https://raw.githubusercontent.com/wcharczuk/go-chart/master/_images/goog_ltm.png)
2016-07-08 05:37:57 +02:00
2016-07-17 05:53:46 +02:00
Two axis:
2016-07-08 05:37:57 +02:00
2016-08-07 07:00:22 +02:00
![](https://raw.githubusercontent.com/wcharczuk/go-chart/master/_images/two_axis.png)
2016-07-08 07:30:16 +02:00
2016-07-29 04:17:35 +02:00
# Other Chart Types
2016-07-08 07:30:16 +02:00
2016-07-29 04:17:35 +02:00
Pie Chart:
2016-07-08 07:30:16 +02:00
2016-08-07 07:00:22 +02:00
![](https://raw.githubusercontent.com/wcharczuk/go-chart/master/_images/pie_chart.png)
2016-07-17 05:53:46 +02:00
2016-08-07 07:00:22 +02:00
The code for this chart can be found in `_examples/pie_chart/main.go`.
2016-07-29 04:19:26 +02:00
2016-07-30 18:39:50 +02:00
Stacked Bar:
2016-08-07 07:00:22 +02:00
![](https://raw.githubusercontent.com/wcharczuk/go-chart/master/_images/stacked_bar.png)
2016-07-30 18:39:50 +02:00
2016-08-07 07:00:22 +02:00
The code for this chart can be found in `_examples/stacked_bar/main.go`.
2016-07-30 18:39:50 +02:00
2016-07-17 05:53:46 +02:00
# Code Examples
2016-08-07 07:00:22 +02:00
Actual chart configurations and examples can be found in the `./_examples/` directory. They are web servers, so start them with `go run main.go` then access `http://localhost:8080` to see the output.
2016-07-17 05:53:46 +02:00
# Usage
2016-07-08 07:30:16 +02:00
2016-07-17 05:53:46 +02:00
Everything starts with the `chart.Chart` object. The bare minimum to draw a chart would be the following:
2016-07-11 03:36:39 +02:00
2016-07-17 05:53:46 +02:00
```golang
2016-07-11 03:36:39 +02:00
2016-07-17 05:53:46 +02:00
import (
...
"bytes"
...
"github.com/wcharczuk/go-chart" //exposes "chart"
)
2016-07-11 03:36:39 +02:00
2016-07-13 07:18:34 +02:00
graph := chart.Chart{
2016-07-13 07:19:49 +02:00
Series: []chart.Series{
2016-07-17 05:53:46 +02:00
chart.ContinuousSeries{
XValues: []float64{1.0, 2.0, 3.0, 4.0},
YValues: []float64{1.0, 2.0, 3.0, 4.0},
2016-07-13 07:19:49 +02:00
},
},
}
2016-07-14 21:41:56 +02:00
2016-07-17 05:53:46 +02:00
buffer := bytes.NewBuffer([]byte{})
err := graph.Render(chart.PNG, buffer)
```
2016-07-14 21:41:56 +02:00
2016-07-17 05:53:46 +02:00
Explanation of the above: A `chart` can have many `Series`, a `Series` is a collection of things that need to be drawn according to the X range and the Y range(s).
2016-07-14 21:41:56 +02:00
2016-07-17 05:53:46 +02:00
Here, we have a single series with x range values as float64s, rendered to a PNG. Note; we can pass any type of `io.Writer` into `Render(...)`, meaning that we can render the chart to a file or a resonse or anything else that implements `io.Writer`.
2016-07-16 02:00:50 +02:00
2016-07-17 05:53:46 +02:00
# API Overview
2016-07-16 02:00:50 +02:00
2016-07-17 05:53:46 +02:00
Everything on the `chart.Chart` object has defaults that can be overriden. Whenever a developer sets a property on the chart object, it is to be assumed that value will be used instead of the default. One complication here
is any object's root `chart.Style` object (i.e named `Style`) and the `Show` property specifically, if any other property is set and the `Show` property is unset, it is assumed to be it's default value of `False`.
2016-07-16 02:00:50 +02:00
2016-08-07 07:00:22 +02:00
The best way to see the api in action is to look at the examples in the `./_examples/` directory.
2016-07-16 02:00:50 +02:00
2016-07-08 05:37:57 +02:00
# Design Philosophy
I wanted to make a charting library that used only native golang, that could be stood up on a server (i.e. it had built in fonts).
The goal with the API itself is to have the "zero value be useful", and to require the user to not code more than they absolutely needed.
# Contributions
This library is super early but contributions are welcome.