quiver is a little command-line tool to plot many arrows with varying positions, lengths, shapes and colors. The plot is specified by a JSON file and saved to a PNG image.

• Build
• Usage
• Spec file
• Arrow shape
• License

Requires CMake and C++17 compiler.

$ git clone https://github.com/snsinfu/quiver-plot.git
$ cd quiver-plot
$ mkdir _build
$ cd _build
$ cmake .. -DCMAKE_BUILD_TYPE=Release
$ make -j
$ ./quiver

Pass quiver specification file as an argument to the command and you get a PNG image.

$ quiver spec.json
$ ls
spec.json  spec.png

The quiver specification is a JSON file. Below is a minimum example that produces red, upward arrow and black, downward arrow. See Spec file section below for full details. More examples.

{
    "rendering": {
        "pixels_per_length": 100,
        "x_range": [-2, 2],
        "y_range": [-1.6, 1.6]
    },

    "style": {
        "background_color": [1, 1, 1],
        "arrow_color": [0, 0, 0],
        "shaft_width": 0.2
    },

    "arrows": [
        {"x": -1, "y": 0, "dx": 0, "dy":  1.5, "c": [1, 0, 0]},
        {"x":  1, "y": 0, "dx": 0, "dy": -1.5}
    ]
}

A spec file describes the style and data of arrows to plot in the JSON format. The quiver program accepts the following keys. Detailed descriptions follow.

{
    "rendering": {
        "pixels_per_length": /* pixel density of the output image */,
        "x_range": /* range of x coordinate values */,
        "y_range": /* range of y coordinate values */,
        "output": /* output file name */
    },

    "style": {
        "background_color": /* color of background */,
        "arrow_color": /* default color of arrows */,
        "shaft_width": /* width of arrow */,
        "stem_to_shaft_ratio": /* relative width of arrowhead */,
        "head_aspect_ratio": /* aspect ratio of arrowhead */
    },

    "arrows": [
        {
            "x": /* x position */,
            "y": /* y position */,
            "dx": /* x component of vector */,
            "dy": /* y component of vector */,
            "w": /* width */,
            "a": /* aspect ratio */,
            "c": /* color */ 
        }
    ]
}

All keys are optional.

All keys are optional.

See Arrow shape section below for detailed description of the geometry of arrow.

x, y, dx and dy are required. Other keys are optional.

The shape of an arrow is controlled by four independent parameters: length, shaft_width, stem_to_shaft_ratio and head_aspect_ratio.

• length is computed by sqrt(dx*dx + dy*dy) for each arrow. It is the distance from the end of the shaft to the pointy end of the arrowhead.
• shaft_width specifies how fat the arrow looks. The w key of each arrow overrides this parameter.
• stem_to_shaft_ratio specifies the relative width of the arrowhead. Must be 1 or larger. Arrows usually look good with this parameter set to 3-5.
• Setting head_aspect_ratio to a small value makes the arrowhead pointy. The a key of each arrow overrides this parameter.

If length is so small that the shaft and the arrowhead cannot be drawn in the specified shape, quiver omits the shaft and only draws a downscaled arrowhead. The aspect ratio of the head is unchanged.

Note: If you plot arrows with varying shaft widths, you may want to scale head_aspect_ratio linearly or with the square root of shaft_width, thus contracting the arrowhead as arrow thickens. These seem to produce aesthetically better-looking results than that without scaling.

MIT License. See also the vendored libraries.