Smrender - A rule-based Renderer for OSM Data

Bernhard R. Fischer

Contents

0  Release Notes

0  Name

0  Synopsis

0  Description

0.0  Rendering Window

   <window>      := <center> | <bbox>
   <bbox>        := <left lower>:<right upper>
   <left lower>  := <coords>
   <right upper> := <coords>
   <center>      := <coords> ':' <size>
   <coords>      := <dec_coords> | <naut_coords>
   <dec_coords>  := <lat> ':' <lon>
   <naut_coords> := ( <naut_lat> ':' <naut_lon ) | 
                    ( <naut_lon> ':' <naut_lat> )
   <size>        := <scale> | <length> 'd' | <length> 'm'

0.0  Options

-a
Smrender
usually processes just those nodes which are located within the window of rendering (see 4.1). This behavior is new with version 3.0. With this option set Smrender processes all nodes independently of their location.
-b color
This option allows to set a background color. The color may be define either as a color preset or an HTML-style definition (see 5.2.1). The default color is white.
Please note that some Shells (such as the bash) interpret the # character if the color is specified in HTML-style. In this case you have to put the color specification under single or double quotes, e.g. -b '#8080ff'.
-D
Smrender
outputs a lot of information to stderr to watch the progress of rendering. It uses the same log levels as defined for syslog (see syslog(3)). By default it logs all messages of the log level LOG_INFO and above. With this option also debug messages are printed. This may be useful if something goes wrong.
-d density
Set the density of the output image. The default value is 300 which is typically used for print-outs in good quality.
-f
Filter data while loading the input file.
With this option a bounding box is used to load just those nodes and ways which are within the selection. The bounding box is 10% larger then the area which resumes from the selected window. This option is useful if huge input data sets are used, such as the planet file.
Please note that this option works only correctly if the nodes and ways are stored in that order in the input file (first all nodes and then all ways).
-g d[:t[:s]]
This option defines the distance d of the grid lines in minutes. The border of the chart (latitude and longitude axis) also depends on this setting. As it is usual for sea charts, there is a major and a minor axis scale, called ticks and subticks. The ticks are defined by t and the subticks are defined by s in minutes. For a correct result, t as well as d should be integral multiples of s.
Note that Smrender internally uses a precision of hundreds of a minute while doing the grid calculation. Thus, the smallest granularity for the grid paramters is 0.01 minutes.
If this option is omitted, Smrender will choose a grid setting dependent on the scale of the output image. For scales below 1:150000 it chooses 5:1:0.2, for scales below 1:250000 it chooses 10:1:0.25, and for scales above 1:250000 it is set to 20:2:0.5.
A grid may optionally be generated with the action grid. See Section 5.2.11.
-G
Do not generate grid nodes/ways. Smrender actually does not render the grid directly onto the output image but rather generates regular OSM nodes and ways. These objects are then rendered in a way as it is defined by the regular rule set. All ways of the grid are tagged with grid=*. Part of the grid are also labels on the border showing degrees in latitude an longitude. The labels are nodes which are tagged with grid=text and the tag name=* containing the value.
-h
Output the list of available options and a short description to stdout and exit.
-i file
This option specifies the name of the input file. If this option is omitted, Smrender reads from stdin.
-k file
With this option Smrender will write a KAP/BSB file to file which can be used with most navigation applications and GPS devices. See Section 8.2 for more details.
-K file
This is similar to option -k but it generates only a KAP/BSB header instead of a complete file. This is useful if you want to use an external tool such as imgkap to create the KAP file from the PNG.
-l
Output page has landscape format rather than portrait, which is default. This option is used only in conjunction with option -P if a literal page format is used.
-o file
Set the filename of the output image. The image will be saved as PNG file. If this option is omitted no image file will be generated.
-O file
Create output PDF file.
-P fmt geom
Select the page format of the output image. The format can be set either named format fmt which has a specific dimension or as geometry geom which contains the width and height of the page in millimeters in the format widthxheight. Fmt currently supports the values A4 up to A0. If this option is omitted, A3 format is selected by default.
If the area to be rendered is specified as bounding box (see Section 4.1) this will most probably colide with the dimension of the page because of the requirements of the projection in which case Smrender will resize the bounding box appropriately. If either the width or the height (but never both) is set to zero then Smrender will calculate the missing dimension according to the bounding box and the projection.
-m Disable memory mapping (see option -M).
-M
This option is mandatory if the input file is larger than the amount of memory available on the rendering system. If the system has enough memory this option can be omitted. Using memory mapping probably is a little bit slower but heavily depends on the operating system. On Linux kernel 2.6.32 there is no significant difference in speed.
In any case, files which are larger then 2 GBytes are only supported on 64 bit operating systems.
This option is now on by default.
-n Some actions of Smrender generate new objects. Negative ids are added to those objects. If this data created by Smrender is fed to another OSM tool negative ids may cause problems. With this option all negative ids are output as positive values.
-r file
This option specifies the file name of the rules file. If it is omitted, Smrender expects the rules file to be named rules.osm.
If file is a directory Smrender will scan it and read all files which match "*osm". The files are read in alphabetical order, simply compared with strcmp(3). Thus, it is suggested to create symbolic links to the files in name it in an appropriate way similar to SysV init scripts.
If you need a more specific order of rule execution you should consider to use the version and/or id fields of the OSM objects (see Section 4).
-R file
This option may be used to save the rules again to another OSM file. This fill will be well-formed in terms of OSM/XML format and may be loaded into JOSM.
-s f
This option is deprecated and is just kept for compatibility. It has no effect. It may be removed in future releases.
-t title
This option generates a descriptional title node which can be rendered onto the final chart. It is as well used as a title for KAP files (see option -k).
-T z ':' dir [ ':' ftype ]
Create tiles suitable for an online viewer into the directory dir. The zoom levels are specified by z which can be either a single value or a range, e.g. 10-15.
The optional parameter ftype sets the file type of the tile images which can be either png (which is default) or jpg.
-u
With this option Smrender will output a set of URLs which are suitable for OSM data download for the area of rendering specified by the window.
-V
With this option set, Smrender parses all arguments, and calculates and prints the rendering parameters to stderr. Then it exits immediately.
-v
With this option Smrender will output the version information of Smrender and libcairo to stdout and exit immediately.
-w file
This option specifies the file name of an output OSM file. Smrender will dump all nodes/ways to this file that have been selected by the import process and all nodes/ways which have been generated during the rendering process.
These nodes/ways include the objects generated for the grid and also the close coastline ways. Thus the output depends on the options -f, -C, and -G.
If this option is omitted, no output will be generated.

0  Ruleset Definition

0.0  Match Operations

• String compare is the most basic match operation. It does an exact case-sensitive string compare. The following tag matches all objects which own the tag seamark:light_character=*.

  <tag k='seamark:light_character' v=''/>

  
  The empty value v='' represents a wildcard match. It matches any string.
  
• Regular expressions are invoked by enclosing the expression within two slashes /.../ as it is usual in Perl and several other languages. The expression is interpreted as a POSIX extended regular expression (see manpages regex(3) and regex(7)). The following expression matches any object which is tagged with either highway=primary or highway=secondary.

  <tag k='highway' v='/^(secondary|primary)$/'/>

  
  
  
• Smrender can interpret tag values as numerical values. Thus, it can do arithmetical comparisons which is less than ( < ) and greater than ( > ).
  The rule has to contain a number enclosed in square brackets. The direction of the brackets denotes the comparison operation; [x] means that the value of the tag should be lower than x and ]x[ matches if the tag value is greater than x. The tag value as well as x are always interpreted as decimal number with double precision.
  Square brackets are used deliberately instead of angle brackets to avoid possible conflicts with the XML format or buggy parsers.
  The following rule matches all objects whose seamark:light:range-value is greater than 7.5.

  <tag k='seamark:light:range' v=']7.5['/>

  
  
• Match inversion is done by enclosing the match expression within exclamation marks. This inverts the match if and only if the expression matched. This means that if a tag would match the expression, the inversion would return "false" (no match). But it would not return "true" (match) if the expression would not match.
  The following expression would match all objects which have a tag with the key seamark:type but its value is neither landmark nor light_major.

  <tag k='seamark:type' v='!/landmark|light_major/!'/>

  
  
• Match exclusion is denoted by enclosing the match expression within tildes. It does not match objects with certain tags. The following rule avoid matching of objects which have a tag seamark=*.

  <tag k='~seamark~' v=''/>

  
  

0.0  Rule Actions

   <action> := <ref> [ ':' <param> [ ';' <param> [ ... ] ] ]
   <ref>    := <func> [ '@' <library> ]
   <param>  := <tparam> | <bparam>
   <tparam> := [ SEP ] <name> [ SEP ] '=' [ SEP ] <value> [ SEP ]
   <bparam> := [ SEP ] <name> [ SEP ] '=' [ SEP ] <bool> [ SEP ]
   <bool>   := 'yes' | 'no' | 'true' | 'false' | <num>
   <num>    := any decimal number
   SEP      := '`' | '"'

0.0.0  Captions

   <action>       := 'cap:' <param>
   <param>        := <name> '=' <value>
   <name>         := 'font' | 'size' | 'key' | 'color' | 'angle' |
                     'weight' | 'phase' | 'valign' | 'halign' |
                     'anglekey'

0.0.0  Drawing and Filling

   <action>       := 'draw:' <param> [ ';' <param> ... ]
   <param>        := <name> '=' <value>
   <name>         := 'color' | 'width' | 'style' |
                     'bcolor' | 'bwidth' | 'bstyle' |
                     'directional' | 'ignore_open'

0.0.0  Calling External Functions

   <definition>  := <function> '@' <library> [':' <param>
                    [ ';' <param> ... ]]
   <library>     := path/name of shared library
   <param>       := <name> '=' <value>

int (*act_function_ini)(smrule_t*);
int (*act_function_main)(smrule_t*, osm_obj_t*);
int (*act_function_fini)(smrule_t*);

typedef struct smrule smrule_t;
typedef struct action action_t;

struct smrule
{
   osm_obj_t *oo;
   void *data;       // arbitrary data
   action_t *act;
};

char *get_param(const char*, double*, const action_t*);
char *get_parami(const char*, int*, const action_t*);

typedef struct osm_obj
{
   // type of object: {OSM_NODE, OSM_WAY, OSM_REL}
   short type;
   // visibility: {0, 1}
   short vis;
   // OSM id
   int64_t id;
   // version, changeset, user id
   int ver, cs, uid;
   // Unix timestamp
   time_t tim;
   // number of tags
   short tag_cnt;
   // Pointer to tags
   struct otag *otag;
} osm_obj_t;

0.0.0  Placing Images

   <definition>  := 'img:' [ <param> [ ';' <param> ... ]]
   <param>       := <name> '=' <value>
   <name>        := 'file' | 'angle' | 'scale' | 'mkarea'

0.0.0  Output of OSM Data

   <definition>  := 'out:' [ <param> [ ';' <param> ... ]]
   <param>       := <name> '=' <value>
   <name>        := 'file'

0.0.0  Adding Tags to Objects

   <action>    := 'settags:' <param>
   <param>     := <name> '=' <value>
   <name>      := 'id'

0.0.0  Standard Shapes

   <action>       := 'shape:' <param>
   <param>        := <name> '=' <value>
   <name>         := 'nodes' | 'style' | 'radius' |  'angle' |
                     'key' | 'weight' | 'phase'

   <tag k='_action_'
        v='shape:nodes=4;radius=2;angle=20;weight=0.3;phase=45'/>

    <node version='-1'>
       <tag k='natural' v='peak'/>
       <tag k='_action_' v='shape:style=triangle;radius=.7'/>
    </node>
    <way>
       <tag k='natural' v='peak'/>
       <tag k='_action_' v='draw:color=#906030'/>
    </way>

0.0.0  Create Formatted Strings

   <action>       := 'strfmt:' <param>
   <param>        := <name> '=' <value>
   <name>         := 'addtag' | 'format' | 'key'

s The string of the value of the tag specified by the respective key is copied to the output string.
f The string of the value of the tag specified by the respective key is interpreted as a floating point number and copied to the output string.
d The string of the value of the tag specified by the respective key is interpreted as an integer number and copied to the output string.
% The percent character is literally copied to the output string.

<node>
   <tag k='natural' v='peak'/>
   <tag k='_action_' v='strfmt:format=%s (%s);
                  addtag=peak_string;key=name;key=ele'/>
</node>
<node>
   <tag k='peak_string' v=''/>
   <tag k='_action_' v='cap:font=serif;size=2;key=peak_string'/>
</node>

0.0.0  Concatenating Split Ways

0.0.0  Executing Programs and Scripts

   <action>       := 'exec:' <param>
   <param>        := <name> '=' <value>
   <name>         := 'cmd' | 'arg' | 'env' | 'osmhdr'

<?xml version='1.0' encoding='UTF-8'?>
<smrender version='0.1' generator='smrender 3.0.r1535'>

<osm version='0.6' generator='smrender'>
<node id="39273652" version="5" timestamp="2009-02-05T06:45:28Z"
   uid="67265" visible="true" lat="44.2128480" lon="15.4482687">
<tag k="created_by" v="Merkaartor 0.13"/>
</node>
</osm>

<status code="200">OK</status>

• . [<code>]
  A single period on a line will provoke Smrender to send the next object which matches the rule. Optionally a numeric code between -128 and 127 can be supplied. 0 is default (if omitted) and simply means success. Smrender appends the status code 200 to each object. If no more objects are available, status code 404 is sent. In that case Smrender waits for a last confirmation through a single period.
  A positiv number indicates an error. Smrender will stop further processing of objects of this rule. The process has the chance to finalize and has to commit this with a single period again. Smrender will close all streams and continue executing the next rule.
  If A negative number is returned, Smrender interpretes this as a fatal error. As a consequence it will imediately stop further processing.
• get (node - way - relation) <id>
  Additional OSM objects can be retrieved with this command.

0.0.0  Special Purpose Actions

• diff ( EXPERIMENTAL)
  This function takes the argument file (exactly like in the function out. See Section 5.2.5.) and infile. It compares the ids of all objects in infile with all objects wich have been loaded by Smrender (option -i) and writes all objects which do not exist to file.
• disable
  This function disables the object to which it is applied. This is done by setting the attribute visible="false". It is intended to be used to completely ignore certain objects during the rendering process. Please note that disabled objects cannot be re-enabled again because the rendering engine completely ignores invisible objects.
• dist_median ( EXPERIMENTAL)
  This function calculates the median of the length of the edges of a way. The result is added to the way within the tag smrender:dist_median=*.
• enable_rule and disable_rule
  These actions take the mandatory argument id which specifies the id of the rule to be enabled or disabled. They actually set the visibility to either true or false (see Section 5). Please note that enabling a rule which would have been rendered before this one according to its version and id is not executed it again.
• exit
  This function forces Smrender to stop. No further rules will be processed and Smrender will create the output files according to the command line options. It behaves exactly like sending the INT signal (pressing ^C, see Section 6).
  This function is mainly intended for debugging rule sets.
• grid
  This action creates a grid exactly like the command line option -g but it provides more options. It provides the parameters margin, tickswidth, and subtickswith to adjust the size of the axis rulers. Values are given in milimeters. Furthermore it provides the parameters grid, ticks, and subticks which work exactly like the command line option (see Section 4.2). Missing parameters are initialized with default values.
• incomplete ( EXPERIMENTAL)
  This action can be applied to relations only. It takes the single parameter file which specifies the name of the output file to which it will write the types and ids of all objects which are listed as members of the relation but are not found in the input data. This may be useful to download this objects to complete the input data if necessary.
  Please note that this currently may not work properly if you specify the same file name in several incomplete-rules.
• inherit_tags ( EXPERIMENTAL)
  This action copies tags from objects to their parent objects. A relation is considered as the parent of all of its members and a way is the parent of all of its nodes.
  There may be a list of one or more key parameters and optionally the parameters object and force. The keys specify which tags from the child (which is to object to which this rule is applied) are copied to its parents. If object is not defined, the tags are copied to all parents of any type. The parameter object may be set to either way or relation in which only the parents of those types are taken into consideration.
  The parameter force may be set to 0 (which is default) or 1. In the latter case inherit_tags will overwrite tags in the parent if they do already exist.
• ins_eqdist ( EXPERIMENTAL)
  This function inserts nodes along a way with equal distances. The distance is given with the parameter distance in nautical miles. The newly inserted nodes inherit all tags from the way and additionally the tags generator=smrender, and distance=*, and bearing=* are added. The latter two tags are set to the appropriate values. The bearing my be used by the function shape (see Section 5.2.7) to create appropriate rotated shapes.
• neighbortile ( EXPERIMENTAL) This is a special function which may be handy in the tile creation process. It creates a directory named "neighbor_tiles" and within this a tile directory tree (zoom/x/y.conf). The files created within this will contain several variables suitable for being sourced in a shell script. The variables in the files specifies the bounding boxes of the tiles in zoom level 10. This function will be improved in future and the file format may change.
• poly_area
  This function calculates the area of closed polygons in nautical square miles. It adds the tag smrender:area=* to the way. The value of the tag contains the area.
• poly_centroid
  This function calculates the centroid of a closed polygon. It then adds a new node at this position. The node will inherit all tags of the polygon. Additionally, the tag smrender:id:way=* is added whose value is set to the ID of the way, respectively.
• poly_len
  This function calculates the length of a polygon in nautical miles. It adds the tag smrender:length=* to the way.
• ruler
  This function allows to generate a metric ruler. It is thought to be used for land maps. It takes the arguments section and count. Section is the length of one section of the ruler in kilometers. Count sets the number of sections.
• set_ccw and set_cw
  Those functions set the direction of a closed way to either clockwise ("cw") or counterclockwise ("ccw").
• split
  This action can be applied to nodes only. It splits all ways at the matching node into two parts.
• refine_poly
  This function smooths the edges of polygons. It may take the function arguments iteration and deviation. The first defines the number of loops of the iterative refinement process (default = 3). The latter defines the maximum deviation of the original polyline in meters (default = 50). This avoids too high distortion of the polylines.
• reverse_way
  This function always reverses a way independent of its current direction.
• zeroway ( EXPERIMENTAL)
  Insert an artificial way of length zero at the matching node. Such a way is a way with two nodes where both nodes have the same position.

0  Signals

0  Extensions

0.0  Libsmfilter and Smfilter

0.0.0  Generating Light Sectors with vsector()

   <param-str>   := <a-v-pair>[';' <a-v-pair>[';' ...]]
   <a-v-pair>    := <attribute> '=' <value>
   <attribute>   := 'a' | 'b' | 'd' | 'r'
   <value>       := decimal number

a
This sets the maximum distance of arc nodes. Basically, the distance is scaled with the radius; the smaller the radius the smaller the distance and vice versa. With large radii the distance of nodes is limited to dist. The value is given in nautical miles.
b
Leading and directional lights are rendered with a bearing line and a small arc at its end. deg sets the angle of this arc to one side which means it is drawn def degrees clockwise and def degress counterclockwise from the bearing line.
d
This defines the arc divisor which is used to determine the distance of the arc nodes. Thus, the node distance equals the radius divided by div. (see also option -a).
r
I light may not have any radius specified since the tag is optional. In such cases smfilter picks radius as default value.

<node>
   <tag k='seamark:type' v=''/>
   <tag 
      k='_action_'
      v='vsector@libsmfilter.so:a=0.05;d=20;r=0.5'
   />
</node>

0.0.0  Compatibility to Smfilter

<?xml version='1.0' encoding='UTF-8'?>
<osm version='0.6'>
   <node>
      <tag k='seamark:type' v=''/>
      <tag k='_action_'
           v='func:vsector@./libsmfilter.so?a=0.05,d=20,r=0.5'/>
   </node>
</osm>

0.0.0  Generating Light Description Strings

0.0.0  Generating Circles around Depth Soundings

0  Examples

tar xvfj icons.tbz2

wget -O cr.osm \
   'http://www.overpass-api.de/api/xapi?map?bbox=15,43.7,15.4,44'

0.0  Generating a PDF

smrender -i cr.osm -o cr.png -P A4 -l 43N52.8:15E12.8:100000

smrender -i cr.osm -O cr.pdf -P A4 -l 43N52.8:15E12.8:100000

0.0  Generating a KAP File

smrender -i cr.osm -d 200 -G -k cr.kap -s 1 43N52.8:15E12.8:100000

0  Files

0  Bugs and Caveats

0  Author

0  Copyright

@  Compiling and Installing

@  Writing Own Rendering Functions

// Use smrender's standard logging. This function is defined in 'smlog.h' and
// works similar to syslog(3).
void log_msg(int, const char*, ...);

// Get an OSM object (OSM_NODE, OSM_WAY, OSM_REL) with the specifed id. This
// function returns a pointer to either an osm_node_t or osm_way_t or_osm_rel_t
// structure on success, or NULL on error.
void *get_object(int, int64_t);

// Add an OSM object to the memory. The function returns 0 on success,
// otherwise -1 is returned. Preexisting objects with the same id are simply
// overwritten.
int put_object(osm_obj_t*);

// These functions return unique ids for nodes and ways.
int64_t unique_node_id(void);
int64_t unique_way_id(void);

// Initialize an OSM object. The number of tags (type short) and the number of
// node references (type int) must be supplied. Currently, the functions always
// return a valid pointer to an object. The objects returned are just partially
// initialized (see 'osm_func.c').
osm_node_t *malloc_node(short);
osm_way_t *malloc_way(short, int);
osm_rel_t *malloc_rel(short, short);

@  FAQ

@.0  Why is Smrender not written in C++?

@.0  Is it possible to create other maps, such as road maps?

@  Todo

• Rendering of rotated (not North-up) maps.
• Dynamic rules; these are rules which are generated during the rendering itself and are applied subsequently.

Footnotes: