Smrender - A rule-based Renderer for OSM Data

Bernhard R. Fischer

Contents

1  Release Notes

2  Name

3  Synopsis

4  Description

   <window> := <lat>:<lon>:<size>
   <size>   := <scale> | <length>'d' | <length>'m'

4.1  Options

-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.
-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.
-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.
-i file
This option specifies the name of the input file. If this option is omitted, Smrender reads from stdin.
-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. If this option is omitted, stdout is used instead.
-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.
-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.
-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.
-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.

5  Ruleset Definition

5.1  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=''/>

  
  

5.2  Rule Actions

   <action>   := <type> ':' <definition>
   <type>     := 'cap' | 'draw' | 'func' |
                 'img' | 'img-auto' | 'mskfill' |
                 'out' | 'settags'

5.2.1  Captions

   <action>       := 'cap:' <definition>
   <definition>   := <font-def> ',' <size> ',' <alignment> ','
                     <color> ',' <rotation> ',' ['*']<key>
   <alignment>    := <horiz> <vert>
   <horiz>        := 'e' | 'w' | 'c'
   <vert>         := 'n' | 's' | 'm'
   <color>        := <col-preset> | <HTML-style color definition>
   <col-preset>   := 'white' | 'black' | 'yellow' | 'blue' |
                     'magenta' | 'brown'
   <rotation>     := 0 - 360 | <auto-rot>
   <auto-rot>     := 'auto' [';' <color> [';' weight [';' phase ]]
   <key>          := name of OSM key

5.2.2  Draw

   <definition>  := <fillstyle> [':' <borderstyle>]
   <fillstyle>   := <style>
   <borderstyle> := <style>
   <style>       := <color> [',' <width> [',' <pattern>]]
   <pattern>     := 'solid' | 'dashed' | 'dotted' | 'transparent'

5.2.3  Calling Functions

   <definition>  := <function> ['@' <libstr> ['?' <param-str>]]
   <libstr>      := 'NULL' | <library>
   <library>     := path/name of shared library
   <param-str>   := <av-pair> [',' <av-pair> [',' ...]]
   <av-pair>     := <attr> '=' <val>

void (*function_ini)(orule_t*);
int (*function)(osm_obj_t*);
void (*function_fini)(void);

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;

• act_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.
• act_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.
• cat_poly()
  This function closes open polygons. To have really closed polygons is highly important because just such polygons can be filled with a background color.
  Polygons which are originally closed, such as the coastline or lakes are very often found as a set of open ways whose beginning and end share the same nodes. This is because different tags may be attached to different parts of the polygon. Furthermore, just partial data sets are used as input because typically just a small area out of the world's data is selected.
  This function finds all adjacent ways and closes them properly. The original data is not changed furthermore it creates and inserts new ways. Those new ways are tagged with all tags that where defined in the rule set plus the tag generator=smrender.
  As already mentioned, the typical application for this function is to close the coastline which will be open in most cases. The coastline is always tagged with natural=coastline.
• set_ccw() and set_cw()
  Those functions set the direction of a closed way to either clockwise ("cw") or counterclockwise ("ccw").
• 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.

5.2.4  Placing Images

   <action>     := <img-act> ':' <file>
   <img-act>    := 'img' | 'img-auto'

5.2.5  Mask-based Filling

<way>
   <tag k='seamark:type' v='depthcont'/>
   <tag k='seamark:depthcont' v='10'/>
   <tag k='_action_' v='mskfill:blue'/>
</way>

5.2.6  Output of OSM Data

   <action>    := 'out:' <filename>

5.2.7  Adding Tags to Objects

   <action>    := 'settags:' <id>

6  Signals

7  Extensions

7.1  Libsmfilter and Smfilter

7.1.1  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='func:vsector@./libsmfilter.so?a=0.05,d=20,r=0.5'
   />
</node>

7.1.2  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>

7.1.3  Generating Light Description Strings

7.1.4  Generating Circles around Depth Soundings

8  Examples

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

./smrender -i cr.osm -o cr.png -P A4 -l -M 43.88:15.213:75000

9  Files

10  Author

11  Copyright

A  Compiling and Installing

B  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);

C  FAQ

C.1  Why is Smrender not written in C++?

D  Todo

• The simple Makefile will be replaced by a configuration by the GNU autotools.
• The GD library will be replaced by the more powerful Cairo library.¹⁶
• The action format will be replaced by a more flexible CSS-style format.
• Rendering of rotated (not North-up) maps.
• Dynamic rules; these are rules which are generated during the rendering itself and are applied subsequently.

Footnotes: