#------------------------------------------------------------ #The cuttlefish Visualization Tool. #Copyright (C) 2006 The Regents of the University of California. # #This program is free software; you can redistribute it and/or modify it #under the terms of the GNU General Public License version 2 as published #by the Free Software Foundation. # #This program is distributed in the hope that it will be useful, #but WITHOUT ANY WARRANTY; without even the implied warranty of #MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the #GNU General Public License for more details. # #You should have received a copy of the GNU General Public License #along with this program; if not, write to the Free Software #Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # #written by Bradley Huffaker # #documention by Joshua Polterock # Bradley Huffaker # Marina Fomenkova # #------------------------------------------------------------ This README.config file documents the cuttlefish configuration file. To understand this cuttlefish configuration and data file and its effect on cuttlefish output, it helps to first understand the general concept of objects and attributes. A description and definition of object-oriented programming and its concepts extends way beyond the scope of this README file. However, for those unfamiliar, I recommend the Wikipedia page at http://en.wikipedia.org/wiki/Object as a reasonable start. Implemented in Perl, cuttlefish makes use of a an object paradigm that defines several classes of objects, each with their own attributes, methods, and defaults. Cuttlefish populates these objects and generates its output image or animation based upon the directives and data it finds in the configuration file. Cuttlefish reads the configuration file to guide its execution as it parses and visualizes the data. Cuttlefish recognizes several objects including 'global', 'map', 'nodelist', 'frame', 'legend', and 'histogram'. Instantiation of these objects in the config file determines the context of execution and the scope of the object attributes. Cuttlefish operates with the concept of a current object and sets the current object to 'global' by default. The 'global' object is actually an instance of a map object and accepts all the attributes associated with the map object. See below for a the description of cuttlefish objects and attributes as well as some example configuration file entries. Cuttlefish understands three types of lines from the cuttlefish configuration file: object instantiation lines, attribute lines, and data lines. Object instantiation lines start with the string 'object' followed by a colon ':' and the string describing one of the defined object types; 'global', 'map', 'nodelist', 'frame', 'legend', or 'histogram'. Attribute lines start with a non-digit character string that names the attribute followed by a colon ':' and the value assigned to the attribute. Each object type has a list of recognized attributes. Finally, data lines (which apply only to nodelist and frame objects) begin with a digit [0-9] (these act as node identifiers) and contain the appropriate values relative to the object context. Cuttlefish parses data lines based on the current object, which gets set by the last object instantiation line. Data lines allow you to input information about nodes into the nodelist object and assign node values in a frame. Note: cuttlefish is data agnostic. However, the values in your objects must accummulate. Cuttlefish only works well with data that accumulates because of the way maps get rendered. Because geographic regions may collapse into single pixels, when multiple nodes display in the same pixel, cuttlefish sums the values associated with the multiple nodes. Therefore, cuttlefish vizualization only works for values that have this cummulative property, i.e. number of hosts, byte counts, packets, etc... Cuttlefish treats lines beginning with the pound character '#' as comments and ignores all following text until it reaches the end-of-line. Cuttlefish concatenates the following line onto the current line if the current line ends with the backslack '\' character. ================================================================== === Object Descriptions === ================================================================== global The global context acts as a default map. This context sets global attributes as well as recognizing all of the attributes defined by the map object below. Cuttlefish draws this object in the background. map A map object (usually) displays a rectangular map of some portion of the world defined by the minimum and maximum lattitudes and longitudes. This object sets attributes associated with a single, current map. Switching to a differenct object context closes the current map object and ends access to its attributes. image This context includes an image (e.g. a logo) from an external file in the output image or animation. Cuttlefish scales the image to match the width and height given in the list of image attributes. nodelist This context allows the user to set attributes associated with nodes that get assigned values in later frame objects. There is only one global nodelist object. Subsequent will not create new nodelists. frame This context allows the user to set node:value pairs associated with a specific time. The frame object contains a list of node:value pairs at a given point in time. The gap between the current frame's time stamp and the following frame's time stamp determines the duration of the frame. Instantiation of a frame object starts a new frame and ends access to the last frame's attributes. Each frame object instantiation line includes a time stamp in the form of either a 'date' or 'time' attribute of the form: date:YYYYMMDD HH:MM:SS sets the unix time stamp for the frame from the year/month/day hour/minute/sec local time. time:\d+ sets the time stamp for the frame directly from the local unix time. legend The legend object maps colors to data value ranges. This context allows the user to set the attributes associated with the legend in the image or animation. Regardless of the number of legend objects created they will also display the same information. histogram The histogram object displays the data total value displayed in all maps across time. This context allows the user to set the attributes associated with the histogram in the image or animation. Since the histogram display the global total across the whole visualization the information display in multiple instances of histogram will be the same. ================================================================== === Object Attributes === ================================================================== ---------------------------------------------------------------------- --- global attributes --- --- These attributes apply to the global object. Multiple --- --- instantiations replace any previously set global attributes. --- ---------------------------------------------------------------------- delay: The number of millisecond delay between frames. frame-rate: The number of frames generated for each data frame found in the file. If the number is greater than 1, extra frames get generated by interpolating between the existing frames. object: The current object context: one of 'global', 'map', 'nodelist', 'frame', 'legend', or 'histogram'. output: The filename of the output GIF image file. bar_height: The height of the bars in the histogram object. width: The width of the output GIF image. If not set, Cuttlefish creates an image with the minimum width necessary to contain the defined map(s), histogram, and legend objects. height: The height of the output GIF image. If not set, Cuttlefish creates an image with the minimum height necessary to contain the defined map(s), histogram and legend objects. map-attributes The global object context can include any of the map object attributes below. Global map attributes get inherited by downstream map objects. Color related attributes get inherited by map, legend, and histogram objects. ------------------------------------------------------------------------ --- map attributes --- --- Instantiation of a map object draws a new map in the image. --- --- Each call to this object draws a new map, the attributes of --- --- which get set only for the current map. --- ------------------------------------------------------------------------ x: The offset on the x axis from the left of the output image. y: The offset on the y axis from the top of the output image. image: The filename of the background image. image-geo: This attribute describes the rectangle of longitudes and latitudes included in this map. label: This displays a label on the map. x and y are relative to the map, not the overall image. The label attributes include: x: position of the label along the x axis. y: position of the label along the y axis starting from the top left corner. font: [giant, large, medium, small, or tiny] sets the font size for this label. type: if the 'type' directive is given on the configuration line, Cuttlefish ignores the user-defined and uses the string generated by . Cuttlefish currently only recognizes one 'date' type: date - if the 'date' type is used, it dynamically creates a string representing the current frame's timestamp. the string displayed at the label location. The can be any user-defined string that follows the attributes described above. It may not contain a ':' character. width: Width of the display map. Cuttlefish will scale the image to fit the set width. If width is set and height is not, the height will be set as the scaled height of the input image. height: Height of the display map. Cuttlefish will scale the image to fit. If height is set and width is not, the width will be set as the scaled width of the input image. node-size: Sets the maximum size in pixels of the nodes drawn on the map. When nodes get drawn as circles (see node-type below), node-size specifies the maximum diameter of the circle. When nodes get drawn as bars, node-size specifies the maximum height. node-size-scale: Sets the scaling of the size across the value range to either linear or log. node-type: Sets the shape of the nodes when drawn on the map. bar - a bar which grows upwards from the geographic point as the value increases. circle - a circle centered on the geographic point which grows as the value increases. night-color: This sets the color of the "night" area. day-color: This sets the color of the "day" area. foreground-color: This sets the color of the text. background-color: This sets the color of the background. ------------------------------------------------------------------------ --- image attributes --- --- Instantiation of a image object draws a new image onto the --- --- final output image. Unlike a map this image is not changed --- --- in any way and has no lat/long so contains no nodes. --- ------------------------------------------------------------------------ x: The offset on the x axis from the left of the output image. y: The offset on the y axis from the top of the output image. image: The filename of the image. width: Width of the display map. Cuttlefish will scale the image to fit the set width. If width is set and height is not, the height will be set as the scaled height of the input image. height: Height of the display map. Cuttlefish will scale the image to fit. If height is set and width is not, the width will be set as the scaled width of the input image. ------------------------------------------------------------------------- --- histogram attributes --- --- Instantiation of a histogram object draws a new histogram in --- --- the image. Cuttlefish can draw the histogram multiple times --- --- in the image, but all histograms derive from a single object. --- ------------------------------------------------------------------------- x: The offset on the x axis from the left of the output image. y: The offset on the y axis from the top of the output image. x-axis: Sets the x-axis. The units selected for display will be added to the end of the . y-axis: Sets the y-axis. width: Sets the width of the histogram. height: Sets the height of the histogram. foreground-color: This sets the color of the text. background-color: This sets the color of the background. ---------------------------------------------------------------------- --- legend attributes --- --- Instantiation of a legend object draws a new legend in --- --- the image. Cuttlefish can draw the legend multiple times --- --- in the image, but all legends derive from a single object. --- ---------------------------------------------------------------------- x: the offset on the x axis from the left of the output image. y: the offset on the y axis from the top of the output image. x-axis: Sets the x-axis, the units selected for display will be added to the end of the . y-axis: Sets the y-axis. width: Sets the width of the histogram. Although the width must be longer than the the bar height. height: Sets the height of the histogram. foreground-color: This sets the color of the text. background-color: This sets the color of the background. ----------------------------------------------------------------------- --- nodelist attributes --- --- Instantiation of the nodelist object creates a new list of --- --- nodes that receive values in the frame contexts. Cuttlefish --- --- expects each data line to contain one node per line. --- ----------------------------------------------------------------------- option(s) One node per line. node-key - any string without white-space that begins with a digit [0-9]. name: - if name is not defined, cuttlefish uses . --------------------------------------------------------------------- --- frame attributes --- --- Instantiation of the frame object starts a new frame and --- --- ends the last frame. Each node gets assigned a single --- --- value per frame. A duplicate value on a node replaces any --- --- previously assigned values. --- ---------------------------------------------------------------------- This assigns the value to node-key, Negative values are not allowed. ===================================================================== === Example cuttlefish config file === ===================================================================== output:cuttlefish.20050713 frame-rate:1 output:temp.gif object:map label: x:20 y:20 This is a label label: x:20 y:160 type:date image:images/world-water.jpg x: 0 y: 0 image-geo: -90 -180 90 180 width:600 object:map image:images/world-water.jpg x: 600 y: 0 label: x:10 y:10 This is in the little image image-geo: -90 -180 90 180 width:200 object:histogram x: 600 y: 100 x-axis: dates y-axis: bytes width: 240 height: 100 object:legend x: 600 y: 200 y-axis: bytes height: 100 object:nodelist 0 35.51 139.39 1 25 100 object:frame time:1120460400 0 25 1 4 object:frame time:1120464000 0 15 1 1