CartoType uses XML style sheets to control the appearance of maps. Features that can be controlled include the following:
Structure of a style sheet
Macros
Dimensions and units
Limits
Colors
Fonts
Labels
Scales
Levels
Projections
The <defs> section
The <layer> section
Displaying highlighted routes, pushpins, user-created data and other
auxiliary data
The <labelLayer> section: a special layer for
icons and labels
Drawing polygons using the <shape> section
Drawing roads and other lines using the <line> section
Drawing icons for points of interest using the <icon> section
Specifying icons using the <svg> section
Bridges and ramps
Tunnels
Arrows to show the direction of one-way streets
Repeated symbols along a
linear feature
Dashed lines
Distinguishing attributes using <condition> sections
Road types
US Census Dept. Types
OpenStreetMap Types
Here are three maps of the same area drawn using different style sheets.
Dimensions are specified using numbers followed by optional units. A number without a unit refers to pixels. Sometimes units are not allowed, as for example in opacity levels, which are dimensionless. Where units are allowed, you can use any of the following:
There are also some special units allowing you to scale features logarithmically so that their sizes are exaggerated at small scales. They are useful for making major roads stand out.
For example, if the scale is 1:10000 and the unit m2 is used, the number of meters is multiplied by √10000 = 100 before being converted to pixels. If you want a size representing 30 meters at 1:10000, use the dimension "0.3m2". At a smaller scale the size will represent a larger number of map meters. For example, at 1:50000 the dimension "0.3m2" represents 0.3 × √50000 = 0.3 × 223 = 67 meters. So although the scale has been reduced fivefold, the size of the feature is reduced by the square root of this ratio: √5 or 2.23.
The m3 and m4 units given even greater exaggerations at smaller scales. If the unit m3 is used instead of m2 in the example above, the feature is reduced in size by the cube root of 5 or 1.71, and the unit m4 gives a reduction by the 4th root of 5 or about 1.5.
Dimensions can optionally be followed by limits: minimum and maximum values. For example, it is useful to specify a label size in map meters, but clamp it to a certain range of sizes, avoiding lettering that is too small to read, or so large as to be ugly and obtrusive. For example:
font-size="300m,8pt,24pt"
sets a label size to 300 map meters but clamps it to the range 8pt...24pt. It is legal to omit the third (upper) limit, as in:
width="45m,2pt"
Colors are RGBA (red, green and blue components plus an 'alpha' or opacity level), and can be specified in these ways:
Apart from colors there are patterns, which need not be plain colors. Anywhere a color is used you can also use a pattern. Patterns are referenced by name using the form 'url(#name)'. The pattern must be defined and named before it is used. The <defs> section is the best place for this.
Fonts are specified using a subset of the CSS font style attributes. For details see Labels.
Objects used more than once can be defined in a <defs> section. An objects must be defined before any layers in which it is used. The following types of objects can be defined in the <defs> section: macros, hachures, icons, patterns and strings.
Macros define named sections of a style sheet for re-use multiple times (full description here).
The
hachure used in the example to the right is specified like this:
<hachure id="other-area-shading" width="1pt" interval="4pt" color="brown" opacity="0.4"/>
The <hachure> attributes are
An icon in a <defs> section is defined using the <icon> tag in the way described below. The only additional attribute it needs is an <id>, which is the name used to reference it elsewhere.
Example: US interstate highway shield icon:
<!-- Interstate highway shield -->
<icon id="interstate-shield" width='100m,20pt'>
<svg width='115' height='115'>
<path d="M 15 0
A 75 75 121.76 0 0 3 21
L 112 21
A 75 75 -121.76 0 0 100 0
A 75 75 0 0 1 57.5 0
A 75 75 0 0 1 15 0 z" fill="#ed1f23" />
<path d="M 2 24
A 75 75 51.16 0 0 57.5 115
A 75 75 -51.16 0 0 113 24 z" fill="#494ea0" />
<path d="M 3 21 L 112 21 L 113 24 L 2 24 z" fill="white" />
</svg>
</icon>
The
tree pattern in the example to the right is specified like this:
<pattern id="mixed-wood-pattern" icon="mixed-wood-icon"/>
All it needs is an <id> and an <icon>. The icon, defined using SVG in the <defs> section in the way described above, is tiled to make a repeating pattern. Later on in the style sheet the pattern is used like this instead of a color to fill polygons in the park layer:
<layer name="park">
<shape fill="url(#mixed-wood-pattern)"/>
<label font-size="300m,8pt,24pt" color="darkgreen"
glow="white" case="title" position="centralpath"/>
</layer>
You can define strings used as paths in a <defs> section like this:
<def id='arrow' string='M -450 -50 V 50 H 250 L -100 400 H 50 L 450 0 L 50 -400 H -100 L 250 -50 H -450 Z'/>
This defines a general-purpose arrow that will not stick outside its stroke if drawn using units of 1/1024 of the stroke width. You can then use it, for example, in a road layer, like this:
<oneWayArrow path='#arrow' gap='2500' fill='teal' opacity='0.5' isLabel='yes'/>
A layer is a named set of map objects of a common type, like roads, parks, or stations. Layers are drawn in the order in which <layer> sections appear in the style sheet. The <layer> attributes are:
The roadflags attribute is a mask that specifies how a non-road layer uses road attributes for levels, tunnels, bridges and ramps. It overrides the default value, or any global value set in <CartoTypeStyleSheet>. It is ignored for the 'road' layer, which always uses road attributes.
The value '#FFFFFFFF' (the # indicates a hexadecimal number) tells CartoType to use the tunnel, bridge, ramp and level attributes for a non-road layer. The value 0 states that none of these attributes are to be used.
You can control the the level, tunnel, bridge and ramp settings separately. The road level is kept in bits 12-15 (mask = #F000), the tunnel flag is bit 0 (mask = #1), the bridge flag is bit 16 (mask = #10000) and the ramp flag is bit 6 (mask = #40). For more details, see TRoadType in the API documentation.
Road layers are special. They must have the name road to indicate that they are to be treated as such when the <line> section is interpreted, and they always use the level, tunnel, bridge and ramp road attributes.
Depending on which sort of objects you expect to find, or wish to draw, in a layer, you should define <shape>, <line> and <icon> sections to specify their appearance:
CartoType applications that do navigation or route-finding need to highlight the current route, display points of interest and addresses selected by the user, and draw other temporary, fast-changing or custom data.
You can do this in a completely flexible way using an auxiliary map database supplied to CartoType at map drawing time. For example, to highlight a route, you could create a memory-resident map database (using the class CMemoryMapDataBase), add the layer "route" to it, and arrange for this database to contain one or more line objects representing the current route, if any.
You then add a layer section for the "route" layer to the style sheet, in a convenient place: probably after all other ordinary layers but before <labelLayer/>.
When a map is drawn and an auxiliary database is supplied as well as the main database, for every layer in the style sheet both databases are searched for matching objects. Objects from the main database are drawn first, then objects from the auxiliary database.
Because of this ordering, if you want to display highlighted icons that override icons from the main database, it is necessary to create a separate layer for the highlighted icons and place its <layer> section before the section referring to the main database, so that the highlighted icons are displayed first. Because of the rule preventing icons from overlapping, the icons for objects in the main database will not appear.
Here is a sample layer for highlighted routes:
<layer name="route">
<line width="18m,3pt" fill="teal" opacity="0.9"/>
</layer>
All icons and labels are collected and drawn as a separate layer, which is drawn when the <labelLayer> section is interpreted. Icons are drawn immediately before labels. The <labelLayer> tag has no attributes, so you just place
<labelLayer/>
in the style sheet, at the same level as other layers. Normally it is the last item in the style sheet.
You can achieve various special effects by using more than one <labelLayer/> tag. Each label layer draws all the icons and labels that have been stored since the last label layer if any. One application for this feature is to draw icons and labels for routing information independently of all others, and overlapping them.
The <shape> section in a <layer> controls the drawing of polygons. The <shape> attributes are
Example:
<shape fill="lightgray" border="darkgray" borderWidth="10m" opacity="0.5"/>
The <line> section in a <layer> controls the drawing of lines, the most important of which are roads. Some attributes apply only to roads. The <line> attributes are
Example of a line that is not a road (in this case, a river):
<line width="20m" fill="lightblue"/>
Example of a line that is a road (in this case, a secondary road):
<line width="22m,2pt" fill="orange" border="black" borderWidth="5%"
centerLine="white" centerLineWidth="5%"/>
Example of a railway drawn using white dashes with a grey border and background:
<line width='12m,2pt' border='grey' borderWidth='10%,0.7,2' fill='white' dashArray='5,5'/>
The <icon> section in a <layer> controls the drawing of icons for point objects. Icons are specified using SVG (Scalable Vector Graphics). The <icon> attributes are:
Every <icon> section that does not load a predefined icon using the ref attribute must contain an <svg> section defining the icon using a subset of the Scalable Vector Graphics language. CartoType supports the following SVG graphic elements fully: <g>, <rect>, <circle>, <ellipse>, <line>, <polyline>, <polygon>, and <path>, and partially supports <text>.
Here is a sample <icon> section containing some SVG code to draw a large blue letter H to indicate a hospital:
<icon width='70m,16pt,100pt'>
<svg width='80' height='100'>
<g stroke='blue' stroke-width='20'>
<line x1='10' y1='0' x2='10' y2='100'/>
<line x1='70' y1='0' x2='70' y2='100'/>
<line x1='10' y1='50' x2='70' y2='50'/>
</g>
</svg>
</icon>
Graphics can be used to indicate bridges and ramps (roads connecting limited-access roads like motorways to other roads). They consist of an optional shadow under the bridge, and optional lines at the side of the bridge, with user-definable ends.
Bridge graphics are drawn for roads with the bridge attribute, and ramp graphics are drawn for those with the ramp attribute.
The bridge graphics above are drawn using this style:
<bridge width='45m,2pt' border='dimgrey' borderWidth='14%,1' endPath='l 512 512' maxScale='50000'/>
You use the <bridge> or <ramp> tag inside a <layer> tag (or inside a <condition> in a layer). The <bridge> and <ramp> attributes are:
For all the dimensions, percentages are relative to the width of the road.
Tunnels can be shown by fading the road, drawing it as a dashed line, or both. Graphics can be drawn to show the mouths of the tunnel.
The tunnel named IJ-TUNNEL above shows all three of these methods and is drawn using this style:
<tunnel dashArray='1,1' mouth='dimgrey' mouthWidth='20%,1' mouthPath='m 0 512 a 512 512 0 1 1 0 -1024'/>
You use the <tunnel> tag inside a <layer> tag (or inside a <condition> in a layer). The <tunnel> attributes are:
You can use the <oneWayArrow> section to define an arrow symbol to be drawn to show the direction of one-way streets. The <oneWayArrow> attributes are:
Example: a broad transparent yellow arrow:
<oneWayArrow path="M 0 50 H 300 L 40 300 H 180 L 505 0 L 180 -300 H 40 L 300 -50 H 0 Z"
fill="yellow" opacity="0.5"/>
If you use <oneWayArrow> on a layer other than "road" it is treated as meaning <repeatedSymbol> and the symbols are unconditionally drawn along the path in the direction in which it is defined.
You can draw repeated symbols along any linear feature. For example, national frontiers are sometimes emphasized using small crosses, and cross-ties can be drawn along railway lines. The syntax is exactly the same as for the <oneWayArrow> attribute on roads, except that you use <repeatedSymbol> instead of <oneWayArrow>. You cannot use both <oneWayArrow> and <repeatedSymbol> for a road.
This feature can be used to place arrows along route lines overlaid on the map by means of of an auxiliary map database.
Dashed lines are specified using a syntax similar to that of SVG. Use the attribute dashArray in the <line> or <shape> tag. The value is a comma-separated list of dash and gap sizes, relative to the line width (e.g., the value 2 means a dash or gap twice as long as the line width).
The railway line below is drawn as a dashed line with a border, using this code in the style sheet:
<layer name='railway'>
<line width='12m,2pt' border='grey' borderWidth='10%,0.7,2' fill='white' dashArray='5,5'/>
<label font-size='75%,8pt' glow='white' color='black' case='assume-title'/>
</layer>
White dashes are drawn over a grey border; when there are dashes, the border
is also the colour between the dashes.
Map objects in a single layer often have different attributes. For instance, roads have a RoadType attribute giving the importance of the road, whether it is one-way, whether it has a central divider, etc. These attributes affect the way the road is drawn.
You use <condition> sections inside <layer> to treat objects with differing attributes in different ways. Each <condition> section is like an embedded <layer> section for only those objects with the specified attributes.
A <condition> section inherits all attributes defined in the containing <layer>, unless it is nested inside another condition, in which case it inherits from the containing condition. Conditions may be nested up to 15 levels deep.
There is only one <condition> attribute:
test: the value is a string representing the condition.
Conditions can test integer values for equality, inequality, and membership of a range. The syntax of the value
string is
attrib_name{mask} relation value
or, for a range of values, or even a list of ranges of values
attrib_name{mask} relation range { ; *range}
that is, one or more ranges, separated by semi-colons, where a range is either a single value or low-value,high-value.
The relation can be any one of these:
= equal to
!= not equal to
< less than
<= less than or equal to
> greater than
>= greater than or equal to
and value is either
The mask is an optional hexadecimal number preceded by a '#'. If it's present it is ANDed with the value of the attribute before the comparison is made. For example, to check whether bits 8...15 of an attribute called 'MyAttrib' have the value 100(hex), use the test 'MyAttrib#FF00=#100'.
Ranges are meaningful only with the relations = (equal to) and != (not equal to).
This is hard to understand without an example. Here is the road layer from a style sheet formerly used by the CartoType demo programs:
<layer name="road">
<line width="30m" fill="orange" border="black" borderWidth="5%"/>
<label font-size="75%,8pt"/>
<condition test="RoadType=#400,#BFF">
<scale max="50000"/>
<line width="18m" fill="yellow" border="black" borderWidth="5%"/>
<label font-size="75%,8pt" maxScale="15000"/>
<oneWayArrow path="M 0 50 H 300 L 40 300 H 180 L 505 0 L 180 -300 H 40 L 300 -50 H 0 Z" fill="teal" opacity="0.5"/>
</condition>
<condition test="RoadType#FF00=#300">
<scale max="100000"/>
<line width="22m,2pt" fill="orange" border="black" borderWidth="5%" centerLine="white" centerLineWidth="5%"/>
<label font-size="75%,9pt"/>
<oneWayArrow path="M 0 50 H 300 L 40 300 H 180 L 505 0 L 180 -300 H 40 L 300 -50 H 0 Z" fill="teal" opacity="0.5"/>
</condition>
<condition test="RoadType#FF00=#200">
<line width="30m,2pt" fill="tomato" border="black" borderWidth="5%" centerLine="pink" centerLineWidth="5%"/>
<label font-size="75%,10pt"/>
<oneWayArrow path="M 0 50 H 300 L 40 300 H 180 L 505 0 L 180 -300 H 40 L 300 -50 H 0 Z" fill="yellow" opacity="0.5"/>
</condition>
<condition test="RoadType#FF00=#100">
<line width="45m,2pt" fill="mediumturquoise" border="black" borderWidth="5%" centerLine="white" centerLineWidth="5%"/>
<label font-size="75%,10pt"/>
<oneWayArrow path="M 0 50 H 300 L 40 300 H 180 L 505 0 L 180 -300 H 40 L 300 -50 H 0 Z" fill="yellow" opacity="0.5"/>
/condition>
</layer>
The first condition has the test "RoadType=#400,#BFF", meaning that only roads with road types in the range 400 (hex) to BFF (hex) inclusive are drawn by the specifications in this condition. These are minor and unclassified roads, and are drawn by this style sheet in yellow and not drawn at smaller scales than 1:15000.
Here is an example showing the inheritance of attributes from the containing layer:
<layer name='waterway'>
<label font-style='italic' color='blue' case='assume-title' glow='white'/>
<!-- RIVER -->
<condition test='Type#FFFF0000=riv'>
<line width='20m,1pt' fill='skyblue'/>
<label font-size='75%,8pt' maxScale='1000000'/>
</condition>
<!-- CANAL -->
<condition test='Type#FFFF0000=can'>
<line width='8m,1pt' fill='skyblue'/>
<label font-size='75%,8pt' maxScale='1000000'/>
</condition>
<!-- STREAM -->
<condition test='Type#FFFF0000=str'>
<line width='8m,1pt' fill='skyblue'/>
<label font-size='75%,8pt' maxScale='250000'/>
</condition>
<!-- DRAIN -->
<condition test='Type#FFFF0000=dra'>
<line width='4m,1pt' fill='skyblue'/>
<label font-size='75%,8pt' maxScale='25000'/>
</condition>
</layer>
And here is an example of a nested condition:
<!-- UNCLASSIFIED AND TERTIARY -->
<condition test='RoadType#F00=#400'>
<scale max='400000'/>
<line width='25m,0.5pt' fill='ivory' border='black' borderWidth='8%,0.7,2'/>
<label font-size='70%,8pt' glow='white' color='black' case='assume-title' maxScale='20000'/>
<oneWayArrow path='#arrow' gap='2500' fill='teal' opacity='0.5' isLabel='yes'/>
<bridge width='38m,2pt' border='black' borderWidth='14%,1' endPath='l 512 512' maxScale='50000'/>
<tunnel dashArray='1,1' fill='grey' mouth='black' mouthWidth='20%,1' mouthPath='m 0 512 a 512 512 0 1 1 0 -1024'/>
<!-- TERTIARY -->
<condition test='RoadType#F80=#400'>
<line fill='khaki'/>
</condition>
Here, tertiary roads are exactly the same as unclassified roads except for their fill color, so a lot of unnecessary repetition is avoided. But note that all the nested tests must succeed for this to work. In this example, the test RoadType#F00=#400 selects both unclassified and tertiary roads, while RoadType#F80=#400 selects tertiary only. When the map is drawn, objects are matched to the innermost test that succeeds.
Road types are as defined in the enumerated type CartoType::TRoadType:
enum TRoadType
{
/** The major road type is held in the high 8 bits. */
EMajorRoadTypeMask = 0xFF00,
/** The minor road type flags are held in the low 8 bits. */
EMinorRoadTypeMask = 0x00FF,
/** Roads of unknown type. */
EUnknownMajorRoadType = 0,
/** Primary road with limited access (motorway, freeway, etc.). */
EPrimaryLimitedAccessRoadType = 0x100,
/** Primary road without limited access: UK 'A' road. */
EPrimaryUnlimitedAccessRoadType = 0x200,
/** Secondary road: UK 'B' road. */
ESecondaryRoadType = 0x300,
/** Local road or town or city street. */
EMinorRoadType = 0x400,
/** Byway: road or track passable only by 4WD vehicles. */
EBywayRoadType = 0x500,
/** Access ramp to limited access road. */
EAccessRampType = 0x600,
/** Service road or access road. */
EServiceRoadType = 0x700,
/** Vehicular Ferry route. */
EVehicularFerryRoadType = 0x800,
/** Passenger-only Ferry route. */
EPassengerFerryRoadType = 0x900,
/** Path or walkway for pedestrians. */
EPathRoadType = 0xA00,
/** Stairway or escalator for pedestrians. */
EStairwayRoadType = 0xB00,
/** A bit flag for roads separated by a central divider. */
ESeparatedRoadTypeFlag = 1,
/** A bit flag for roads in a tunnel. */
ETunnelRoadTypeFlag = 2,
/** A bit flag for underpassing roads. */
EUnderpassRoadTypeFlag = 4,
/** A bit flag for roads with a central railway or tramway. */
ECentralRailLineRoadTypeFlag = 8,
/** A bit flag indicating that the road is one-way in the direction in which it is defined. */
EOneWayForwardRoadTypeFlag = 16,
/** A bit flag indicating that the road is one-way in the reverse direction to that in which it is defined. */
EOneWayBackwardRoadTypeFlag = 32,
/** A bit flag to allow access ramps (links) to be marked as sub-types of a major road type. */
ELinkRoadTypeFlag = 64,
/**
A bit flag to allow a distinction to be made between grades of road, within the major road type.
It allows OpenStreetMap data to distinguish trunk roads from primary roads in a backward-compatible way.
*/
ELowerGradeRoadTypeFlag = 128,
};
CTM1 map files created from US Census Dept. TIGER data use the attribute 'CFCC', which gives the feature type. CFCC stands for Census Feature Class Code.
The original CFCC codes are made from an uppercase letter followed by a two-digit number. The codes used in CartoType's CTM1 data format are entirely numeric. The uppercase letter is replaced by one or two digits, using the range 1...26 for the letters A...Z. Thus A08 (road with rail line in center) becomes 108, and X00 (feature not yet classified) becomes 2400.
For roads, CFCC codes are translated into CartoType road types, which are explained in the previous section.
There is a list of CFCC codes at http://www.census.gov/geo/www/tiger/tigerua/ua2ktgr.pdf (in Chapter 3).
CTM1 map files created from OpenStreetMap data (OSM files in XML format) use the attribute Type. This 32-bit value contains a value in its upper 15 bits that encodes a three-letter tag that is a mnemonic for one of the tags used in the OSM file. The encoding is done like this: for the purpose of explanation here is a C macro that takes three lower-case letters:
#define OsmType(A,B,C) ((((A)-'a') << 27) | (((B)-'a') << 22) | (((C)-'a') << 17))
However, you don't have to work with the actual numeric values because you can use the three-letter tag on the right hand side of a test in a <condition>.
Here are the OpenStreetMap types that are currently defined and used by generate_map_data_type1.
EAerodrome = OsmType('a','e','r'),
EAirTerminal = OsmType('a','t','e'),
EBeach = OsmType('b','e','a'),
EBridleway = OsmType('b','r','i'),
EBusStation = OsmType('b','s','t'),
EBuilding = OsmType('b','u','i'),
ECanal = OsmType('c','a','n'),
ECemetery = OsmType('c','e','m'),
ECity = OsmType('c','i','t'),
ECommercial = OsmType('c','m','r'),
ECoastline = OsmType('c','o','a'),
ECollege = OsmType('c','o','l'),
ECommon = OsmType('c','o','m'),
EContinent = OsmType('c','o','n'),
ECounty = OsmType('c','o','u'),
ECarPark = OsmType('c','p','k'),
ECountry = OsmType('c','r','y'),
EDock = OsmType('d','o','c'),
EDrain = OsmType('d','r','a'),
EFarm = OsmType('f','a','r'),
ECycleway = OsmType('c','y','c'),
EFootpath = OsmType('f','o','o'),
EForestry = OsmType('f','o','r'), // OSM name="forest"
EGolfCourse = OsmType('g','o','l'),
EHamlet = OsmType('h','a','m'),
EHeath = OsmType('h','e','a'),
ERailwayHalt = OsmType('h','l','t'),
EHospital = OsmType('h','o','s'),
EIndustrial = OsmType('i','n','d'),
EIsland = OsmType('i','s','l'),
ELocality = OsmType('l','o','c'),
EMarsh = OsmType('m','a','r'),
EPark = OsmType('p','a','r'),
EQuarry = OsmType('q','a','r'),
ERegion = OsmType('r','e','g'),
ERetail = OsmType('r','e','t'),
ERailway = OsmType('r','l','y'),
EResidential = OsmType('r','s','d'),
EReservoir = OsmType('r','s','v'),
ERiver = OsmType('r','i','v'),
ERunway = OsmType('r','u','n'),
ERiverBank = OsmType('r','v','b'),
ESchool = OsmType('s','c','h'),
ESportsCenter = OsmType('s','p','o'),
ESportsPitch = OsmType('s','p','p'), // OSM name="pitch"
ESteps = OsmType('s','t','e'),
EStadium = OsmType('s','t','m'),
EState = OsmType('s','t','a'),
ERailwayStation = OsmType('s','t','n'), // OSM name = "station"
EStream = OsmType('s','t','r'),
ESuburb = OsmType('s','u','b'),
ETown = OsmType('t','o','w'),
EVillage = OsmType('v','i','l'),
EWater = OsmType('w','a','t'),
EWood = OsmType('w','o','o')