# Picviz: The Fine Manual

## by Sebastien Tricaud (toady@gscore.org)

This manual is about the right use of Picviz: its architecture, language, rendering and what you can do with it

## Introduction

Picviz goal is to provide a language, a library and applications to realize parallel plot coordinates graphs easily. To help you realizing your graph, it delivers a set of types you can decide your axes to be. Everytime a value is added, it is positioned accordingly.

Since Picviz is focused on computer security data analysis, its default types are time, ip address, string or various kind of numbers.

## The PCV language

The PCV language goal is to remain as simple as possible to map your values on your axes. It is made of at least two sections that are axes definitions and their attached data. Two extra sections are possible: header to define special properties related to your image and engine, to change the picviz engine behavior.

The order of each section is only important for axes and data, but a good PCV file should look like:

    header {
     ...
    }
    engine {
     ...
    }
    axes {
     ...
    }
    data {
     ...
    }

## Header section

The header section can now only set the graph title. So this only way to use it is like this:

    header {
       title = "Graph title";
    }

## Axis section

The axis section is appears like this:

    axes {
     ...
    }

Where '...' is your definition of axes types and properties. For example, if you want to add two axes able to receive data ranging from 0 to 65535, you should declare it as:

    axes {
            integer myaxis;
            integer thesecond;
    }

And if you want to set a label on your axis to ease its recognition, you may add the label property:

    axes {
            integer myaxis [label="My first axis"];
            integer thesecond [label="The next one"];
    }

### Axis type

Every axis my be declared with a type, which can be:

Type | Range | Description
timeline | "00:00" - "23:59" | 24 hours time value
integer | 0 - 65535 | Integer number
string | "" - "The competent programmer is fully aware of the limited size of his\\ own skull. He therefore approaches his task with full humility, and avoids clever tricks like the plague." | A string value
short | 0 - 32767 | Short number
ipv4 | 0.0.0.0 - 255.255.255.255 | IPv4 address
gold | 0 - 1433 | A small value, where the gold number is the maximum
char | 0 - 255 | A value that can be seen as a char

### Axis properties

- label: sets the label to display with the graph

## Data section

The data section positionates values on the axes. Its syntax is:

The value must fit the axis type. And the properties are applied on the whole line. If we deal with a string, we map the string value with our special string: "The competent programmer is fully aware of the limited size of his own skull. He therefore approaches his task with full humility, and avoids clever tricks like the plague.". This is a special trick to avoid your biggest string to be always on the maximum value to give you an idea when dealing with several string axes. However, if among data a bigger string is set, it will become the biggest reference for the other strings.

### Data properties

- color: sets the line color (red, blue, ...)

### Getting dirty

Right now, you have enough to get started, so we first want to map values on three kinds of axes: time value, integer and a string. The PCV file 'ex1.pcv' code should look like:

    header {
            title = "My first graph";
    }
    axes {
            timeline time [label="Time"];
            integer  nb   [label="Number"];
            string   str  [label="My string"];
    }
    data {
            time="0:00",nb="4242",str="This is my first string";
            time="12:00",nb="4242",str="This is my second string" [color="red"];
            time="15:00",nb="45986",str="This string is a bit bigger than the other ones" [color="blue"];
    }

Then, using the pcv program like this:

    $ pcv -Tsvg ex1.pcv > ex1.svg

And it should look like this:
As you can see, the way strings are mapped inform you wether a string is close to an other or not. This is useful to discover a ssh scanning activity based on, say, a username change. The data here where of course choosen to be easily recognized using the color property to understand what you see.