= The Picviz language =

== Introduction ==

The Picviz language is a graph description language, similar to graphviz dot language. With Picviz, the language can be divided in four sections:
 * '''header''' (optional): contains the graph title, default background etc..
 * '''engine''' (optional): changes Picviz engine internals (not recommended)
 * '''axes''' : variable and properties setting for each axis
 * '''data''' : plot your data on previously defined axes

{{{
header {
    title = "Plot my IP";
}
axes {
    timeline t;
    ipv4    i;
}
data {
   t="14:42", i="123.2.3.4";
   t="15:45", i="200.123.4.6";
layer broadcasts {
   t="15:45", i="255.255.255.255";
}
}
}}}

== Properties ==

Properties can be set for the header and for each axis and for each line. They are a set of key = "values" coma separated between brackets:
{{{
[label="foobar",color="orange"]
}}} 

=== Header properties ===

In the '''header''' section, following properties are available:
|| '''Name''' || '''Description''' || '''Defaults''' || '''Example''' ||
|| height || Image height || 300 || height = "500"; ||
|| width || Image width || 500 || width = "800"; ||
|| bgcolor || Background color || white || bgcolor="#ff0000"; ||
|| bgalpha || Background alpha channel || 1 (Opaque) || bgalpa="0"; ||
|| header-height || Image header height || 50 || header-height="100"; ||
|| filter || Inline filter || None || filter="plot > 50% on axis 3 and value = 'error' on axis 6"; ||
|| logo || Logo image to embed || None || logo="logo.png"; ||
|| logo.x || Logo X position || 0 || logo.x = "50"; ||
|| logo.y || Logo Y position || 0 || logo.y = "300"; ||
|| hide-layers || Choose layers you want to hide || None || hide-layers = "broadcasts,foobar"; ||
|| font.color || Global font color || black || font.color = "red"; ||
|| font.size || Global font size || 12 || font.size = "20"; ||

=== Axis properties ===

In the '''axes''' section, following properties are available: '''label''','''relative''' and '''print'''. That you can use like this:
{{{
axes {
   timeline t [label="Time"];
   ipv4     src [label="Source IP",print="false"];
   string   data [label="Data",relative="true"];
}
}}}

 * '''label''' is the text that is written on top of the axis on the generated image.

 * '''relative''' spreads the string variable as far possible from each other (incompatible with the basic string algorithm).

 * '''print''' will not print values on this axis when asking to print values (option -a in the pcv binary)

=== Variables ===

Each axis must have a variable. Choose among:
|| Type || Range || Description ||
|| timeline || "00:00:00" - "23:59:59" || 24 hours time value ||
|| years || "1970-01-01 00:00:00" - "2023-12-31 23:59:59" || Years of time value ||
|| integer || 0 - 65535 || Integer number ||
|| string || "" - "No specific limit" || A string value ||
|| short || 0 - 32767 || Short number ||
|| ipv4 || 0.0.0.0 - 255.255.255.255 || IPv4 address ||
|| gold || 0 - 1433 || Small value ||
|| char || 0 - 255 || Tiny value ||
|| enum || anything || Enumeration ||
|| ln || 0 - N || ln(x) ||
|| port || 0 - 65535 || Display ports numbers with privileged ports on half of the axis ||


=== Line properties ===

In the '''data''' section, only the following property is available: '''color''', '''penwidth'''. That you can use like this:
{{{
data {
    t="12:30", src="192.168.1.1" [color="red"];
    t="12:42", src="192.168.1.23" [color="blue",penwidth="3"];
}
}}}

Following colors are available: "white","black", "red", "green", "blue", "yellow", "grey", "turquoise", "pink", "orange", "darkblue", "darkgreen", "darkred", "brown".

|| '''Name''' || '''Description''' || '''Defaults''' || '''Example''' ||
|| color || Line color || black || [color="#ff0231"]; [color="(0.3,0.1,1.0)"]; [color="red"] ||
|| penwidth || Line width || 0.2 || [penwidth="0.1"]; ||
|| inlayer || Layer selection || NULL || [inlayer="secondscan"]; ||