README

A command-line tool that converts .vec files into SVG. The VEC format is a custom line-based vector format used by the pMetro program for station schemes. This tool produces SVG output that visually matches what the native viewer renders.

Installation

Requires PHP 8.4+ and Composer.

Global install (recommended):

composer global require 4dd/m2vec

Make sure ~/.config/composer/vendor/bin (or ~/.composer/vendor/bin) is in your PATH.

Local install:

composer require 4dd/m2vec
./vendor/bin/m2vec path/to/scheme.vec path/to/scheme.svg

Usage

Convert a single file:

m2vec path/to/scheme.vec path/to/scheme.svg

Batch-convert a list of source|destination pairs (one per line, # for comments, - to read from stdin):

m2vec --batch=jobs.txt

VEC format overview

A .vec file is a sequence of one-line commands. Tokens are separated by spaces or commas (interchangeably). Numbers are integers or decimals; coordinates are in pixels with the origin at the top-left.

The file is cp1251-encoded; m2vec converts every line to UTF-8 once and the rest of the pipeline operates in UTF-8.

Comments

Lines starting with ;, =, -, or : are treated as comments and rendered into the SVG as . The documented prefix is ; only; the others appear throughout the corpus as visual separators (===), hand-disabled commands (--Line ...) and a typo in several spb files (:). The native viewer ignores all of them, so we do too.

Drawing-state commands

Command	Effect on subsequent commands
`Size WxH`	Canvas dimensions in pixels. Required, must appear once.
`PenColor RRGGBB`	Stroke colour (hex). `-1` means "no stroke" (transparent).
`BrushColor RRGGBB`	Fill colour. `-1` means "no fill" (transparent).
`Angle deg`	Rotates the entire remaining canvas around its centre.
`Opaque pct`	Opens a translucent group at `pct%` opacity. `Opaque 100` closes the group AND resets pen+brush to defaults — the native viewer scopes drawing state inside an opaque block.
`Image path`	Embeds an external raster image as an `<image>` element.

Geometry commands

All shape commands optionally accept a trailing odd-token "stroke width" after the coordinate pairs.

Command	Arguments	SVG output
`Line`	`x1,y1, x2,y2[, ...xn,yn][, w]`	`<polyline>` (stroke only)
`Dashed`	same as `Line`	`<polyline>` with `stroke-dasharray`
`Spline`	2+ points, optional width	`<polyline>` refined by 4-point interpolating subdivision (8 inserted vertices per input segment)
`Polygon`	3+ points, optional width	`<polygon>` with current pen + brush
`Stairs`	`p1, p2, p3[, w]` (3 points define a parallelogram)	A polyline of stair "rungs" perpendicular to the p1→p2 edge, inset by half a step on both ends
`Arrow`	2+ points, optional width	A `<polyline>` shaft plus an arrowhead at the last point (rotated to match the final segment)
`Ellipse`	`x1,y1, x2,y2[, w]` (bounding box corners)	`<ellipse>`
`Railway`	`railW, sleeperW, step, x1,y1, ...xn,yn[, w]`	Two parallel polyline rails (same subdivision as `Spline`) plus perpendicular sleepers at `step/2, 3·step/2, ...`

Text commands

Command	Arguments	SVG output
`TextOut`	`font, size, x, y, text[, styleFlag]`	`<text>` with `font-family`, `font-size` and style attrs
`AngleTextOut`	`angle, font, size, x, y, text[, styleFlag]`	`<text>` wrapped in a `transform="rotate(...)"` group

Notes on text:

The text field may be wrapped in single or double quotes ('...' or "...") to preserve embedded commas. The wrapping quotes are stripped from the output.
Literal \n (backslash + n) inside the text becomes a <tspan> line break with dy="1.2em".
styleFlag is a bitmask in [1, 15]: 1 = bold, 2 = italic, 4 = underline, 8 = strikethrough (combinable).
Font size is divided by 1.2 before emitting, which empirically matches the native viewer's rendering at typical sizes.

Interactive / spot commands

These are flagged regions used by the original viewer for click handlers. m2vec renders them as plain visible shapes (without the click target).

Command	Arguments	SVG output
`SpotRect`	`x, y, width, height[, action]`	`<rect>` with current pen + brush
`SpotCircle`	`r, x, y[, action]`	`<circle>` filled only (no stroke)

The pMetro readme documents SpotCircle as x, y, r, but every real file uses r, x, y and the native viewer follows that order — m2vec matches the data.

What is NOT supported

Action handlers on Spot commands. The action field (typically ShowMessage ...) is parsed but not emitted; the SVG is static.
Viewer-only metadata like raw byte-level encoding artefacts beyond cp1251.
Custom fonts. The font field is passed through to font-family; the rendering depends on the consumer's available fonts.

Error handling

Invalid lines are never fatal. They become:

A [WARN] file:line — message line on stderr.
An inline  comment in the SVG at the same position.

Unknown commands, malformed coordinates, and missing required fields are all reported this way so that one bad line never blocks the rest of the file.

4dd / m2vec

Maintainers

Package info

Statistics

Security