PointLabeller

Creates vector point labels using Mapnik as a placement engine. PointLabeller positions labels around input points using collision-aware placement, then extracts the resulting placements as true vector geometry — fully styleable, exportable to any format, and free of overlap.

Unlike LabelPointReplacer, which generates label geometry from a fixed text-and-anchor calculation, PointLabeller delegates placement to Mapnik and recovers vector positions from the rendered output. The result is professional cartographic placement with directional priority, automatic font size reduction when space is tight, and clean fallback behavior for points that cannot be placed.

Useful for any pipeline that needs vector text geometry rather than rendered pixels: print maps, PDF atlases, GIS deliverables with editable labels, and downstream processes that consume label position as data.

How does it work

PointLabeller runs a four-stage pipeline:

1. Placement. Each input point is sent to Mapnik with the configured font, label text, size ladder, and direction priority. Mapnik attempts placement in each direction in order, reducing font size if no direction succeeds at the current size, until either a placement is found or all sizes in the reduction ladder are exhausted.

2. Rasterization. Successful placements are rendered to an internal raster at the resolution set by Rasterization Cell Spacing. Each label is rendered in a unique color so individual labels can be separated downstream.

3. Vectorization. The raster is converted back to vector geometry. Each color region becomes a bounding box around its label, preserving the position Mapnik chose.

4. Typographic correction. Bounding boxes are corrected from raster pixel-space to true font-space using the four ratio parameters (Cap Height, Ascender, Descender, x-Height). The output is a vector label whose insertion point and size match what a downstream renderer would produce for the same font and size. The four ratio parameters are font-specific and must be calibrated once per font. See Usage Notes: Calibration Workflow.

Configuration

Input Ports

Input

Point features. Non-point features are routed to the Rejected port.

Output Ports

RasterLabels

The Mapnik-rendered raster output as a single raster feature. Useful as a reference layer, for visual QA, and as the source-of-truth overlay in

Calibration mode.

VectorLabels

The extracted vector label geometry.

NotLabelled

The input features that did not receive a label with current settings.

Rejected

Input features that could not be labelled, with an _error_message

attribute identifying the cause. Common reasons:

NON-POINT — feature is not a point geometry

EMPTY_LABEL — Label parameter evaluated to empty or null

Parameters

Labelling Mode

Selects between two modes:

Calibration — produces an overlay of vector labels on the Mapnik raster

for visually tuning the typographic ratios

Placement — produces final vector labels for downstream use

Run Calibration once per font, then switch to Placement for production output.

See Usage Notes: Calibration Workflow.

Font Name

The font used by Mapnik for placement. Type a font name directly or use the

ellipsis (...) to open a system font dialog.

The font must be installed on the system running the transformer. If it is not, Mapnik silently substitutes a system default and the typographic ratio calibration becomes invalid for the substituted font, producing miscalibrated output. Confirm the font is available on every machine the workspace will run on — including FME Flow engines.

Label

The text to render. Most commonly an attribute reference,

but any FME expression combining attributes and literals is accepted — for

example, @Value(city) + ', ' + @Value(state).

Cap Height Ratio, Ascender Ratio, Descender Ratio, x-Height Ratio

Font-specific typographic ratios used to convert raster bounding boxes into

true font-space measurements. All four are fractions of the em square, in

the range 0–1.

Typical values:

Cap Height Ratio: 0.65–0.76

Ascender Ratio: 0.65–0.78 (close to or slightly higher than Cap Height)

Descender Ratio: 0.18–0.25

x-Height Ratio: 0.47–0.6

These must be calibrated per font. See Usage Notes: Calibration Workflow.

Directions

Comma-separated list of direction codes, ordered by priority. Mapnik tries

each direction in order at the current font size; if none succeed, the size

is reduced and the list is tried again. Available codes:

N, S, E, W — above, below, right, left of the point

NE, NW, SE, SW — diagonal positions

X — centered on the point

A typical priority list places preferred positions first: E,W,N,S,NE,SE,NW,SW.

For full behavior, see Mapnik's text symbolizer, placements documentation.

Maximum Label Size

The largest font size, in map units, at which Mapnik will attempt placement.

The actual rendered size at 100% may be slightly larger because Mapnik's

internal sizing is approximate at large sizes — the difference is negligible

at typical map scales.

Choose a value matched to your map's scale and label density. See

Usage Notes: Label Size and Reductions.

Allowed Font Size Reductions, %

Comma-separated list of percentages of Maximum Label Size to try when

placement fails at full size. The transformer attempts 100% first, then

each percentage in the list in order.

A typical ladder is 90,80,70,60,50 — five fallback steps before giving up.

For full behavior, see Mapnik's text symbolizer, placements documentation.

Rasterization Cell Spacing

Resolution of the internal label raster, in map units. Smaller values produce higher quality at the cost of speed and memory.

The right value depends on the smallest font size you expect — that is, Maximum Label Size multiplied by the smallest percentage in your Font Size Reductions ladder. The smallest font size divided by cell spacing should be at least 30, and ideally 50 or more for reliable extraction. Below 24, labels begin to merge, split, or disappear.

For example, with Maximum Label Size 48000 and a reductions ladder ending at 50%, the smallest label is 24000 map units. Cell spacing of 500 gives a ratio of 48 (clean), 750 gives 32 (good), 1000 gives 24 (marginal). See Usage Notes: Rasterization and Label Quality.

Extents Scale Factor

Multiplier applied to the bounding box of all input points to define the

rasterization extent. Values above 1.0 expand the extent so labels near the

edge of the data are not clipped.

Default 1.3 handles most cases including long multi-word labels at the data edge (such as "San Buenaventura (Ventura)"). Values above 1.5 are rarely needed and increase raster size and processing time quadratically. If labels near the edge of your data are being cut off, increase by 0.1–0.2 at a time.

Label Offset Along X, Label Offset Along Y

Displacement of the label from the point, passed to Mapnik as dx and

dy. Values are in raster pixels — actual map-unit displacement scales

with Rasterization Cell Spacing. Both values must be non-zero for

direction-based placement to apply.

For full behavior, see Mapnik's text-dx / text-dy documentation.

Advanced

These parameters extend default character-class detection for fonts where the default sets are incomplete. Most fonts do not require additions.

Ascenders (bdfhklti()[]{} are always included)

Additional characters to treat as ascenders. Type single characters as a single word or separated by spaces or commas. Case-sensitive. Common additions: capital J and Q in serif fonts where these letters ascend above cap height; old-style numerals 6 and 8. A character may appear in both Ascenders and Descenders if it both ascends and descends — for example, capital J in Baskerville.

Descenders (gjpqy,;()[]{} are always included)

Additional characters to treat as descenders. Same input format and rules as Ascenders. Common additions: capital J and Q in serif fonts (Baskerville, Georgia, Times); italic lowercase f; old-style numerals 3, 4, 5, 7, 9.

Calibration Workflow

PointLabeller positions and sizes vector labels using four font-specific

typographic ratios: Cap Height, Ascender, Descender, and x-Height. These

ratios describe how a font's character heights divide the em square, and

they vary from font to font. Before producing final output for a new font, run Calibration mode to tune the ratios for that font.

Calibration is a one-time step per font. Once calibrated, save the ratio

values and reuse them whenever that font is selected.

What calibration looks like

In Calibration mode, the transformer outputs both the Mapnik raster and the extracted vector labels overlaid on the raster. The raster shows where Mapnik placed each label and at what size; the vectors show what

PointLabeller extracted using the current ratio values.

When the ratios are correctly calibrated, vector labels sit tightly above the raster labels, which appear as a subtle black shadow rather than as

visibly offset or sized text. When the ratios are off, you will see one of

these patterns:

Vectors larger than the raster text — at least one ratio is too small.

The raster bounding box is being divided by a too-small denominator,

inflating the computed font size.

Vectors smaller than the raster text — at least one ratio is too large.

Vector vertical position offset from the raster — the height ratios

are roughly right but the y-offset for descenders or ascenders is off;

this typically means Cap Height and Ascender Ratios are internally

inconsistent (for example, Ascender set too close to or below Cap Height).

Step-by-step

Set Labelling Mode to Calibration.

Set Font Name to the font you want to calibrate.

Run the transformer and inspect the output. Open the result in Data

Inspector with both RasterLabels and VectorLabels visible at the same

time.

Examine labels containing each of the four character cases — they

exercise different ratios:

Caps only (e.g., "PARIS", "USA") — exercises Cap Height Ratio

Ascenders, no descenders (e.g., "Tallinn") — exercises Ascender Ratio

Descenders, no ascenders (e.g., "synonymous") —

exercises Descender Ratio

Both ascenders and descenders (e.g., "Lappeenranta", "Würzburg") — exercises both

Neither (e.g., "enormousness", "vancouver moon") — exercises

x-Height Ratio

Adjust the ratios that correspond to the misaligned cases:

If lowercase-only labels with no ascenders or descenders are

misaligned, adjust x-Height Ratio.

If caps-only labels are misaligned, adjust Cap Height Ratio.

If ascender-only labels are misaligned, adjust Ascender Ratio.

If descender-only labels are misaligned, adjust Descender Ratio.

Re-run and re-inspect. Iterate until vectors form a tight shadow behind

the raster across all four character cases.

Switch Labelling Mode to Placement for production output.

Validation rules

Ascender Ratio should be greater than or equal to Cap Height Ratio. In

some fonts they are nearly equal; Ascender Ratio should never be less.

All four ratios fall in the range 0–1.

Reference values

The following ratios are calibrated for two common system fonts and serve

as starting points for similar fonts:

Font

Cap Height

Ascender

Descender

x-Height

Arial (sans-serif, transformer default)

0.73

0.75

0.19

0.55

Times New Roman (serif)

0.68

0.70

0.20

0.47

For other fonts, start from whichever of these is closer in style

(sans-serif → Arial, serif → Times New Roman) and calibrate from there.

Residual offsets

Even with well-calibrated ratios, small horizontal offsets may appear on

longer multi-word labels — typically a fraction of a character width

across names like "San Pedro de Atacama" or "Saint Petersburg." Several

factors contribute, and they cannot be fully resolved by ratio adjustment:

Anti-aliasing extraction. Mapnik renders text with sub-pixel

precision using alpha and color blending at character edges to

produce smooth output. The vector extraction step works on the solid

interior of each character, which means roughly one pixel of edge

detail is lost on each side.

Kerning differences. Mapnik (the placement engine) and FME's text

renderer (which produces the final geometry) apply slightly different

kerning adjustments for adjacent character pairs in the same font.

Cumulative drift across long multi-word labels is most visible.

Rasterization granularity. Bounding boxes are recovered at Cell

Spacing resolution. Sub-cell-spacing edge positions are rounded to

the nearest grid line.

The combined effect is generally invisible at typical map scales and

acceptable in cartographic output. At fine cell spacing (high

quality-ratio), residual offsets are smaller. At coarse cell spacing

near the quality threshold, they are more pronounced.

Diacritics

Accented capitals such as Á, Č, Š extend above standard cap height in

many fonts. The current calibration model treats these as standard caps,

which produces small height errors for labels containing accented capitals.

For maps with significant Central European, Vietnamese, or other heavily

accented content, expect minor visual offset on those labels.

CRS recommendation.

Use a projected CRS in linear units (meters, feet)

rather than geographic coordinates (latitude/longitude in degrees).

Geographic coordinates work but are harder to tune — the tiny fractional

values required for cell spacing in degrees make parameter selection less

forgiving.

Rasterization and Label Quality

PointLabeller uses an internal raster intermediate to extract vector labels

from Mapnik's placement output. Each label is rendered to the raster in a

unique color, then connected-component analysis recovers a bounding box

per label. The Rasterization Cell Spacing parameter controls the resolution

of this internal raster, and it directly affects whether labels are

captured cleanly.

Choosing a cell spacing

The right value is determined by the smallest font size you expect — that

is, Maximum Label Size multiplied by the smallest percentage in your Font

Size Reductions ladder. The smallest font size divided by cell spacing

should be at least 30, and ideally 50 or more for clean extraction.

Below 24, labels begin to merge, split, or disappear.

Smallest font size / cell spacing

Quality

50 or more

Clean, reliable extraction

30–50

Good, occasional minor artifacts

24–30

Marginal, expect intermittent failures

Below 24

Broken, labels merge, split, or disappear

For example, with Maximum Label Size 48000 and a reductions ladder ending

at 50%, the smallest label is 24000 map units. Cell spacing of 500 gives a

ratio of 48 (clean), 750 gives 32 (good), 1000 gives 24 (marginal).

Cell spacing depends on font size, not absolute scale

Cell Spacing is in map units, but the right value scales with font size,

not with the geographic extent of your data. A national-scale map with

small labels needs finer cell spacing than a regional map with large

labels, even though the national map covers more area.

This also means Cell Spacing depends on your CRS units. The same map in

EPSG:32145 (meters) and EPSG:4326 (degrees) needs cell spacing values that

differ by roughly five orders of magnitude. The 1/30 ratio rule is unit-

independent and works in any CRS.

Performance trade-off

Halving cell spacing roughly quadruples raster size and processing

time. For large datasets, push cell spacing as high as your quality

threshold allows rather than defaulting to the smallest value that works.

On the test dataset (1000 US cities, Maximum Label Size 48000), cell

spacing 500 produces clean output in seconds; spacing 100 produces

identical quality in tens of seconds with no visible improvement.

Use Calibration mode at the cell spacing you intend to use in production.

Calibrating at finer resolution than production runs introduces small

discrepancies between calibrated ratios and actual extraction.

Font-Specific Characters

The Advanced section lets you extend default ascender and descender detection for fonts where the default character classes are incomplete.

When defaults are sufficient

For most upright (non-italic) text fonts using lining numerals (the standard set in Arial, Times, Calibri, Helvetica, and most modern fonts), the default character lists work without additions. Run Calibration with your test labels; if calibration produces a tight shadow across all character cases, the defaults are correct for your font.

Common additions

Three categories of font-specific characters routinely require advanced configuration: Capital descenders. In serif fonts (Baskerville, Georgia, Times New Roman, Garamond), capital J typically has a descender — its lower curve drops below baseline. Capital Q has a smaller tail descender; including it produces a slightly oversized bbox, omitting it produces a slightly undersized bbox at the Q-tail. Most users choose to include J and exclude Q. Italic descenders. In italic styles of many fonts, lowercase f has both an ascender and a descender (the famous double-loop italic f). Add f to descenders when working with italic styles; in upright styles, leave it out. Old-style numerals. Some serif fonts (Georgia is the most common) default to old-style figures, where 3, 4, 5, 7, 9 descend below baseline and 6, 8 extend above x-height. Add these to descenders and ascenders respectively when your labels include numbers and the font uses old-style figures.

Characters that may appear in both lists

A character may appear in both the Ascenders and Descenders lists if it both extends above x-height and below baseline. The most common example is capital J in serif fonts, which both reaches cap height (above x-height) and descends below baseline. Italic lowercase f is another. Including a character in both lists routes labels containing it to the HasAscendersAndDescenders case (height denominator AR + DR), which is correct for any character that spans the full vertical range.

Troubleshooting

Labels appear miscalibrated (vectors don't match raster)

Run Calibration mode and adjust the four typographic ratios for your

font. See Calibration Workflow. If you have already calibrated and

output is still off:

Verify the font is installed on the machine running the workspace

(and on FME Flow engines if applicable). Mapnik silently substitutes

a system default when a font is missing, invalidating calibration.

Confirm Labelling Mode is set to Placement, not Calibration.

Labels merging, splitting, or disappearing

Cell Spacing is too coarse relative to font size. See Rasterization and

Label Quality — the smallest font size divided by Cell Spacing should

be at least 30. Decrease Cell Spacing and re-run.

Many points routed to Not-Labelled

Mapnik could not place these labels at any size in the reduction ladder.

Possible causes:

Points are too dense for the chosen Maximum Label Size — labels

collide at every direction and every size step. Reduce Maximum Label

Size, extend the reduction ladder further down, or thin the input

points.

Direction list is too restrictive — only one or two directions

available. Add more directions to the priority list.

Labels near the edge of the map are cut off

Increase Extents Scale Factor by 0.1–0.2 and re-run. If labels are

extremely long (multi-word with parentheticals), values up to 1.5 may

be needed.

Points with empty labels are processed

Check the Label parameter expression. If you intend to skip points

without label values, route them to a Tester upstream of PointLabeller.

PointLabeller routes empty-label features to Rejected with reason

EMPTY_LABEL, but you may want to filter them earlier in the workflow.

Q-bearing labels in serif fonts look slightly off

Capital Q has a small tail descender that doesn't match the descender

depth of g, j, p, q, y. See Font-Specific Characters > Common

additions. The recommended approach is to omit Q from the descender

list and accept a slight under-extent at the Q-tail.

Lowercase labels with brackets render small

Brackets ( ) [ ] { } extend to approximately cap height in most

fonts. In labels with lowercase letters and brackets but no capitals

(e.g., (ventura)), the current logic treats the top of the bbox as

x-height when it actually reaches cap height. This is a known

limitation; add an uppercase letter to the label as a workaround, or

accept the size discrepancy.

Output looks horizontal when I expect rotation

PointLabeller produces horizontally placed labels only. For rotated

labels along linear features, see LineLabeller.

Performance is too slow

See Performance Tips. The most common cause is Cell Spacing finer

than necessary. Coarsen Cell Spacing toward the quality threshold, then

trim the Font Size Reductions ladder.