bbd

NAME
DESCRIPTION
CATEGORIES
ATTRIBUTES
CONVENTIONS
EXAMPLES
CAVEATS
AUTHOR
SEE ALSO

DESCRIPTION

Sorry - parts of this documentation are still in German...

bbd is a simple format for describing points and polylines for geographic information systems.

Bbd files consist of newline-terminated records in the format:

    Name TAB Category SPACE x,y SPACE x,y ...

Coordinate lines (data lines)

Name

A descriptive name, for example the street name, or (for attribute layers) a description of the attribute category. This field must not contain any TAB characters.

If there is a main name and a descriptive part, then the latter should be separated by a | character. This helps for intelligent labelling, i.e. leaving out unimportant parts if necessary. Example: Ringenwalde|(Uckermark) could be labelled as Ringenwalde or Ringenwalde (Uckermark).

Category

The category of this point or polyline. If the category matches #rrggbb (where rr, gg and bb are hexadecimal values), then this denotes a color for the representation in the Perl/Tk interface. A prefix of F: denotes that the polyline should be treated as a polygon and filled with a solid color. Note that the polygon is always closed, but it is optional to make the first and last the same.

If the category matches forwardcat;backwardcat, then forwardcat applies to the street in forward direction and backwardcat applies to the street in backward direction. Either forwardcat or backwardcat may be empty; in this case the category applies only to the other direction.

The X category should be used if there is no category.

Other predefined categories are listed below. The category should not contain any spaces.

   DRAFT (not yet in use!): Change the category format to:

       <cat> = <onewaycat> ; <onewaycat> |
               <onewaycat>

       <onewaycat> = F=? <basiccat> (: <attrkey> (= <attrval>)?)*

       <basiccat>  = [^:;]+
       <attrkey>   = [^:;=]+
       <attrval>   = [^:;=]+

   Changes for data files:
     F:cat becomes F=cat
     ?::inwork becomes ?:inwork
     F:SW|IMG:church.gif|ANCHOR:s becomes F=SW:IMG=church.gif:ANCHOR=s
   Maybe (no, too much typing):
     #rrggbb becomes X:COLOR=#rrggbb

   cat is now really attr. Reflect in description, maybe also in
   variable names.

x,y

A coordinate. x and y should be integer or float values. The datum and grid of the coordinates should be handled by the software. It is recommended that x and y should denote the easting and northing in meters (as in GKK or UTM). A record may contain an unlimited number of coordinates, though there may be limitations in the interpreting software. See also below for the map directive in Directive lines.

Directive lines

If a line begines with a hash sign followed by a color (#:), then the line is treated as a directive. There are global directives, line directives and block directives. Global directives should be specified at top of the file before the first data line and should be separated by the data lines with an empty directive line. For example:

 #: encoding: utf-8
 #: map: polar
 #:
 ... data lines

Line directives are valid for the next line only:

 #: add_fragezeichen: Is this really correct?
 Main street: bad cobblestone	Q3 13.5,52.5 13.4,52.5

Block directives are valid for the specified block. Block directives are markes as such:

 #: directive_name directive_arguments ... vvv
 ... data lines
 #: directive_name ^^^

The v and ^ markers can be repeated an indefinite number of times, but at least three times.

Directives have always at least the directive name (the first word token in the line) and zero, one or more directive values:

 #: directive_name
 #: directive_name: val1
 #: directive_name: val1 val2

The colon (:) after the directive name is optional. The following is equivalent:

 #: encoding utf-8
 #: encoding: utf-8

Global directives

type: bbd_type

This global directive sets the type of the bbd file. If given then it should be put into the first line to serve as a kind of "magic". A possible type would be bbr or

bbbike
route

, once I get rid of the .bbr format.

map: maptype

This global directive sets the coordinate system of the bbd file. If no map directive is specified, then the proprietary bbbike coordinate system is used. For WGS84 coordinates specified as DDD use the maptype polar.

title: title string

This global directive sets the title or some descriptive text for the file.

It is possible to localize the title by using the title.$lang syntax, e.g.

    title.en: English title
    title.de: deutscher Titel

version: RCS or CVS identifier string

This global directive introduces an RCS/CVS Id string. Not recommended if a modern version controlling system like git is used.

encoding: encoding name

Treat this file as encoded in the given encoding (all names accepted by Perl's Encode may be used, see Encode::Supported). If not set, then iso-8859-1 is assumed.

The degree of support for encodings in bbbike.cgi and the Perl/Tk implementation differs. iso-8859-1 is supported best. utf-8 is considered to work in most, if not all places of the code. Other encodings are at least known to NOT work with the XS implementation for the fast street and point plotting. The pure perl implementation is fine.

listing_sort: sort_method

Define a sorting method for street/point listings. Normally listings will be sorted alphabetically (sort method alphabetic). If the listing should appear as in the bbd file, specify unsorted. natural should be used for "natural" sorting (see Sort::Naturally).

Plotting hint directives

Plotting hint directives are used to control plotting of items. The directives can only be set as global directives. The directives explained below exist in two forms:

directive: ...: The directive is valid for all items (unless overriden by per-category directives).
directive.category: ...: The directive is valid for items with the named category (this overrides directives without category specification).

The list of plotting hint directives:

line_color: color

line_color.category: color

Define the color for line items. color should be in the form #rrggbb.

Example:

 #: line_color: #808080
 #: line_color.cat: #ff8080

Compatibility: category_color.category is still recognized as an alternative to line_color.category. Maybe this will removed some day.

XXX: Maybe use item_color instead of line_color, because colors apply also to points and areas!

XXX: Hmmm, it seems that str_color is (also?) in use, see tmp/streets-accurate.bbd

line_width: width

line_width.category: width

Define the width of line items. The width should either be one value, or six comma-separated values. If it's only one value, then it is taken as the width at approx. 1:17000, and other widths are calculated proportionally to $line_width{default}. If it's six values, then this should represent the widths for the six standard scales defined by bbbike.

line_length: length

line_length.category: length

Define the length of line items. In the Perl/Tk interface this is currently used for oneway and blocked symbols.

XXX: The form with category is NYI!

XXX: Maybe this should make it possible to define lengths for specific zoom levels, like in the bbbike standard definitions.

line_dash: x, y, ...

line_dash.category: x, y, ...

Define the default dash pattern for line items. See DASH PATTERNS in Tk::Canvas for the list integer syntax.

Example:

 #: line_dash: 1,1
 #: line_dash: 2,4

Compatibility: category_dash.category was formerly used instead of line_dash.category and is still recognized, but will be removed some day.

line_capstyle: capstyle

line_capstyle.category: capstyle

Define the capstyle for line items. Valid values are butt, projecting, or round (see Tk::Canvas).

XXX: Currently category_capstyle.category is used instead of line_capstyle.category.

line_arrow: arrowspec

line_arrow.category: arrowspec

Define whether arrows should be drawn on line items. Valid values are none, last, first, or both (see Tk::Canvas).

Example:

 #: line_arrow: last
 #: line_arrow.cat: both

Currently setting the line_arrow directive (without category) to last has also the effect to center to the beginning of a feature selected in the street list of the Perl/Tk application (otherwise the default is the center of the feature).

line_shorten: boolean

line_shorten.category: boolean

Define whether line items should be shortened on both ends.

XXX: Currently category_line_shorten.category is used instead of line_shorten.category.

line_shorten_end: boolean

line_shorten_end.category: boolean

Define whether line items should be shortened at the end.

XXX: Currently category_line_shorten_end.category is used instead of line_shorten_end.category.

line_directed_weight: boolean

line_directed_weight.category: boolean

Define whether lines are directed and present weights.

line_do_offset: boolean

line_do_offset.category: boolean

Define whether lines should be plotted with an offset or not. By default, lines which have a "splitted" category for the forward and backward directory (e.g. A;B) are plotted with an offset, but this can be disabled by explicitely setting line_do_offset to a false value.

item_size: integer

item_size.category: integer

Define the size of items (for example base label font size or the size of point items in pixels).

XXX: The category-less form is NYI! XXX: Currently category_size.category is used instead item_size.category.

item_image: image_name

item_image.category: image_name

Define an image for point items. The image name is usually without suffix and will be searched in the default bbbike image directories, if specified relative.

XXX: The category-less form is NYI! XXX: Currently category_image.category is used instead item_image.category.

item_stipple: image_name

item_stipple.category: image_name

Define a stipple (which is usually an xbm image) for area items.

XXX: The category-less form is NYI! XXX: Currently category_stipple.category is used instead item_stipple.category.

layer_stack: how:tag

Define how the data should appear in the layer stacking order. how is either above or below and tag is another layering tag used in bbbike (some examples are s for the street layer or w for the water layer --- consult the bbbike source, variable @normal_stack_order for more tags).

XXX This is experimental and likely to change!

Line/block directives

by: source

according_to: source

Denotes that the information in the next block or line was provided by source. This may be an email address or full name of an author, an URL providing more information, a Message-Id of a mail or posting, a date, or a combination of all. according_to: is an alias for by:.

by[nocache]: URL>

Like the by directive, but the value must be an URL, and it is marked as non-cacheable (for whatever reasons), but still linkable.

by[removed]: URL>

Like the by directive, but the value must be an URL, and it is marked as removed, probably generating a 404 response or the site does not exist at all.

corrected_by: source previous -> current

Used after a by directive for a correction. It is advisable to put the previous a small note of the previous and maybe also the current entry after the source.

confirmed_by: source

Denotes that the information in the next block or line was confirmed by source.

source_id: id

A special form of a by directive where a formal id can be used. Currently there are three id schemes in use: viz2021 (a pseudo id for VIZ traffic reports), bvg2021 and bvg2024 (BVG traffic reports: prefixed by the affected line, then a #, then the id), and scheme-less (a real VIZ id). Sometimes also other forms of pseudo ids or even URLs are used here.

source_id[inactive]: id

An inactive source id (typically not accessible anymore at the source site and/or expired).

valid: YYYYMMDD-YYYYMMDD

valid: YYYYMMDD-

valid: -YYYYMMDD

Define the validity period of records. Other tools (e.g. grepstrassen) may remove non-valid records automatically.

If the value is preceded by a !, then the validation period is inverted.

Note: in future Strassen::Core may deal automatically (or optional) with removal of non-valid records.

NOTE: Makefile rules don't cope well with the ability that source files are processed differently depending on time.

temporary:

The next block or line is just a temporary feature. Typically there's one large "temporary" block per bbd file, and typically entries within this block are accompanied by next_check directives to specify the end date, so systems like "fragezeichen-nextcheck" can include these entries in their lists.

XXX: why

The next block or line is unsure or unclear information, and usually has to be researched on-site. The why text specifies an additional comment. This note should not appear in the processed data.

Earlier versions also defined unsure as an alias for XXX (or even the other way around), but in reality unsure was almost never used and also never considered in supporting scripts, so its use is now deprecated.

XXX_prog: why

The next block or line contains problematic information due to problems in the using programs, i.e. bbbike and bbbike.cgi.

For example this can be used if stacking information has to be given using ordering in the data file, but bbbike should really have a layer_stack attribute.

In the past it was also used for the cyclepath layer, because of suboptimal rendering in points with large angles (more than 45° or so). Here the layer item has to be broken into two items to fix the rendering problem. But this is solved in bbbike since July 2009.

XXX_indoor: why

The unclear information can only be researched "indoor", and usually not on-site.

XXX_osm: why

An issue in OpenStreetMap data, e.g. incorrectly spelled street name or wrong ways.

alias: name

Define another known name for the next line.

alias_wide: name

Special alias name to be used for "wide region" routings. In "inner city" routing the real name should be used instead.

Examples:

    #: alias_wide: Oranienburg - Bernau (B273)
    Bernauer Str. (B273)	B ...,...

name: lang: name

The name in another language, specified by lang in ISO 639 codes.

oldname: when: name

An old name for the next line. when is a time specification (best: some kind of ISO dates, but this is not yet specified). Unknown dates in when should be marked with a question mark. Multiple oldname directives are allowed for one record.

Examples:

    #: oldname: ?-20001001: Oldname street
    #: oldname: 20001001-2005: Not-so-old-name street

ignore_oldname_file: yes

Ignore this oldname entry when generating the oldnames data file. This is useful if for example only a part of the street was renamed.

ignore_check_net: yes

Ignore this entry for "within network" checks.

section: section name

The next block is part of a named section. Sections may be nested.

ignore

The next line/block is ignored for some processing instructions. For example, "busroute_N" entries in comments_misc-orig are skipped when creating comments_misc.

append_comment: comment

Useful for preprocessing bbd data files to add a comment to each record in the block.

attributes: attribute, ...

attrs: attribute, ...

Define additional attributes for the following line or block. The attributes may be used in a preprocessing script to generate additional layers. attrs is an alias for attributes.

note: string

A free text note, which shouldn't (but may) appear in the processed data.

see_also: string

A free text note, which refers to more information. This should be typically a URL.

last_checked: date

last_checked: date (by: name)

Date (and optionally surveyor) of the last check for a feature. This is useful in conjunction with XXX or add_fragezeichen directives, to generate automatic list of streets to be surveyed again.

next_check: date

Recommended date for a next survey for a feature. This could be for instance the intended finish date of road construction.

For generating survey lists, it could also be useful to generate synthetic next_check directives out of last_checked value, e.g. one month after the last check. The default interval could be set by the check_frequency directive.

check_frequency: daysd

Set a check frequency for the synthetic generationg of next_check directives. If not set, then the default could be one month or so.

next_check_id: identifier

Used to group related to-be-surveyed feature, possibly spread over multiple files. Should be used only if there are really multiple features.

The bbbike emacs major mode generates buttons for these directives; clicking on these buttons would start a search for this identifier over all data files.

also_indoor: spec

Checks which may be done indoor. spec may have the following values:

search term: Link to a search engine with the given search term.
traffic: Link to a traffic map at the coordinate of the item.
url url: Link to a specific URL.
webcam url: Link to a specific URL, which is expected to show webcam imagery.

Currently the script miscsrc/fragezeichen2org.pl may handle also_indoor directives.

as_of: date

Last verified at the given date. The date should be in a ISO-8601-like notation, with possible abbreviations: YYYY-MM-DD or YYYY-MM or YYYY.

The difference between last_checked and as_of is subtle; it is expected that last_checked-tagged entries should be actively checked for changes, and as_of-tagged entries only passively.

Currently as_of directives appear in data/comments_ferry-orig for ferry timetable and fare information.

url: string

An (official) URL referring to more information useful for end users, like opening or operating hours or fees. For other kind information use the by: directive.

add_fragezeichen: string

Some postprocessing code may add the following line with the descriptive text string to the fragezeichen file.

osm_watch: relation|way|node id="element_id" version="version"

osm_watch: note note_id comment_num

osm_watch[closed]: note note_id comment_num

Link the following bbd item to an OpenStreetMap (OSM) element (relation, way, node) or note. version or comment_num specify the latest checked version. The [closed] variant is used for notes which are already closed.

osm_watch directives cause links when editing .bbd files using emacs with bbbike-mode. miscsrc/fragezeichen2org.pl also generates links. miscsrc/check-osm-watch-list.pl may be used to find changed OSM elements and notes (the watch list for this script is created by miscsrc/bbd_to_osm_watch_list).

complete: yes|no

May be used to mark a feature as complete or incomplete (e.g. cycle routes).

priority: string

A priority for checks. The priority string should be something between #A (highest, use for features which are important for many routings) and #D (lowest, use for features which are not used at all for routings, e.g. zebras).

linked: string

May be used for check purposes. Currently only utilized in ortsschilder-orig, where the linked name is to be used to do checks against orte-orig/orte2-orig.

source_file: filename

For generated files: the generated lines originate from the specified filename. This is usually specified as a non-block directive; another source_file directive would switch to a different source file.

source_line: number

For generated files: the generated lines originate at the specified line number. This directive has to be specified together with source_file.

id: string

An identifier string.

osm.highway: string

The value of an OSM highway key. May be used when converting bbd data to osm data, e.g. by bbd2osm.

Obsolete and to-be-decided directives

off: when comment

Currently used in ampeln-orig, needs to be decided on the exact format and even on the directive name. Example entry:

    #: off: night (seen 2001-12-25)

The comment part may be completely missing.

Currently the following labels are used in the when part: night, weekend, holiday, week day names, except_schooltime, except_event, HH:MM-HH:MM.

internal_note: string

A free text note, which must not appear in the processed data. It is just a note for editors.

Currently I think the XXX_... is better suited for this task, as it can give more specific information.

historical_note: string

A free text note with former data regarding the associated record. Sometimes this may also be fetched using the version control system, but this is sometimes cumbersome. Note that old names should instead be specified using the oldname directive.

unverified_by: source

Same as "by:" for unverified data. "Unverified" means that there's no communication channel back to the information provider. Nowadays this would be a couple of "by:" and "add_fragezeichen:" or "XXX:" directives.

XXX_checklater: why

Like XXX, and additionally attach the "checklater" attribute.

This tag is not supported anymore. Instead, use just XXX in conjunction with next_check or last_checked. The current infrastructure (supporting scripts etc.) have better support for this.

XXX_outdoor: why

Deprecated. Usually this is the same as XXX, and scripts don't support this type anymore.

Comment lines

If a line begins with a hash sign (#), then it is treated as a comment. Empty lines are ignored.

ATTRIBUTES

inwork: Marks the map item to be "in work". This could be rendered with an additional "in work" sign along the map item. This attribute is already handled in a couple of data files (fragezeichen, gesperrt, handicap, strassen_bab).
Tu: The map item is in a tunnel. This is already handled in sbahn, rbahn, ubahn, strassen_bab, and wasser*.
Note that not every BBBike renderer may render a tunnel specially. The Perl/Tk application has complete render support for all tunnel categories (see also the below ones). The PDFCairo renderer has simple support for tunnels (drawn as dashed lines). The PDF and GD renderers draw tunnels like normal lines, except for tunneled waterways, which are currently completely ignored. All other renderers (e.g. Mapserver) draw all tunnels like normal lines.
Tu_: The map item is in a tunnel and a tunnel mound should only be drawn at the beginning of the map item.
_Tu: The map item is in a tunnel and a tunnel mound should only be drawn at the end of the map item.
_Tu_: The map item is in a tunnel and no tunnel mounds should be drawn at all.
Br: The map item is on a bridge. This is already handled in strassen_bab.
Eb: The map item is on an embankment (Bahn- oder Straßendamm). This means that the map item is typically over other map items. The attribute is not used yet.
Cu: The map item is in a cutting (Einschnitt). This means that the map item is typically under other map items. The attribute is not used yet.
igndisp: Ignore display. Item will not be rendered, but may be used for other purposes (i.e. routing). See ignrte.
ignrte: Ignore in routing. Item will not be used in routing, but may be used for other purposes (i.e. display). See igndisp.
temp: Mark a "temporary" entry, which is non-recurring. Used in temp blockings. Currently rendered with a "calendar" sign.
night: Mark a temporary blocking which is active only at night. Currently rendered with a "moon" sign.
weekend: Mark a temporary blocking which is active at weekend. Currently not rendered.
clock: Mark a temporary blocking which is recurring. Currently rendered with a "clock" sign.
xmas: Mark a temporary blocking which is active typically before and after Christmas. Currently rendered with a christmas tree sign.
bomb: Mark a temporary blocking due to bomb disposals. Currently rendered with a "bomb" sign.
play: Mark a temporary play street.
mask: Mark a street with mandatory mask-wearing.
sign: Mainly used for roads that will either receive a new street name or have other remarks regarding signage.
alternating: Used for traffic lights which control alternating traffic flow. Very often used together with an "inwork" attribute. Currently rendered as an up/down arrow.

CONVENTIONS

Lines which are to be removed, but still should be kept as a kind of "historical documentation", may be turned into a comment with "REMOVED" as the first word. Multiple lines may be joined into one line, separated by a "---". For example:

    # REMOVED --- #: confirmed_by: me --- old entry X 1234,5678 9876,5432

EXAMPLES

    #: map: polar
    #:
    # a comment
    Dudenstr.	H 13.3857982559056,52.4850047136888 13.3822671967909,52.4849893166144 13.3765591649622,52.4849797043717 13.3721313913775,52.4849830887141 13.3708964575072,52.4850055627098
    Viktoriapark	F:P 13.3770529147335,52.4891642850551 13.376956820767,52.4876188211697 13.3778829456197,52.4875997186591

And a detailed explanation...

    Start of a directive
    v
    #: map: polar
       ^
       Coordinate system of this file is defined as WGS84, DDD

    Start of a comment
    v
    # a comment

(Note that spaces are insignificant in the following examples, but <TAB> and <SPACE> should be inserted)

                              List of coordinates (x,y pairs)
                              v
    Dudenstr. <TAB> H <SPACE> 13.3857982559056,52.4850047136888 13.3822671967909,52.4849893166144 13.3765591649622,52.4849797043717 13.3721313913775,52.4849830887141 13.3708964575072,52.4850055627098
    ^               ^
    Street name     Category (H = main street)

                                   List of coordinates for a polygon
                                   v
    Viktoriapark <TAB> F:P <SPACE> 13.3770529147335,52.4891642850551 13.376956820767,52.4876188211697 13.3778829456197,52.4875997186591
    ^                  ^
    Name of a park     Category (F = area (polygon, Fläche),
                                 P = park)

                    Category (S = S-Bahn, A = Tariff area A)
                    v
    S1,S2,S25 <TAB> SA::Tu_ <SPACE> coordinates ...
                        ^
                        Attribute (Tunnel, only draw tunnel entrance
                                   at beginning)

CAVEATS

Some category values may change. It is likely that either the blocking and/or city category values will change, as both use digits.

AUTHOR

Slaven Rezic <slaven@rezic.de>

bbd

NAME

DESCRIPTION

Coordinate lines (data lines)

Directive lines

Global directives

Plotting hint directives

Line/block directives

Obsolete and to-be-decided directives

Comment lines

CATEGORIES

STREETS

BLOCKINGS

CYCLE PATHS (RADWEGE)

RAILROADS

QUALITY

RIGHT OF WAY

COMMENTS

AREAS

CITIES AND PLACES

MISC

OTHER STANDARD FILES

ATTRIBUTES

CONVENTIONS

EXAMPLES

CAVEATS

AUTHOR

SEE ALSO