.TH TOPOMERGE "1" "January 2021" "" "User Commands"
.SH NAME
topomerge \- merges the source TopoJSON geometry collection, assigning to the
target
.SH SYNOPSIS
.B topomerge
.RI [ options ]
.RI < target = source >
.RI [ file ]
.SH DESCRIPTION
.P
Merges polygons (or meshes lines) from the specified
.I source
TopoJSON geometry collection object, assigning to the
.I target
object.
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
Output usage information.
.TP
.BR \-V , \ \-\-version
Output the version number.
.TP
.BR \-o , \ \-\-out\ \fIfile
Specify the output TopoJSON file name.
Defaults to
.B \-
for stdout.
.TP
.BR \-k , \ \-\-key\ \fIexpression
Specify a JavaScript
.IR expression ,
given a TopoJSON geometry object
.I d
and its zero-based index
.I i
in its parent collection, that determines how geometry objects are grouped
before merging; each group is merged separately.
For example, given a topology of U.S. \fIcounties\fR, where the
.I id
of each county is its five-digit FIPS code, the county boundaries can be merged
into state boundaries by using the first two digits of the county FIPS code,
which represents the state FIPS code:
.IP
.in +4n
.EX
.B topomerge states=counties -k 'd.id.slice(0, 2)' < us-counties.json > us-states.json
.EE
.in
.IP
If a key is not specified, all input geometry objects will be merged together.
For example, this can be used to merge the state boundaries into a single
nation boundary:
.IP
.in +4n
.EX
.B topomerge nation=states < us-states.json > us.json
.EE
.in
.TP
.BR \-f , \ \-\-filter\ \fIexpression
Specify a JavaScript
.I expression
that filters the input geometries before merging or meshing.
In conjunction with
.BR \-\-mesh ,
the
.I expression
is given two TopoJSON geometry objects
.I a
and
.I b
that represent the adjacent features for a given arc segment; if the
.I expression
evaluates truthily, the associated arc segment is retained in mesh.
Otherwise, the
.I expression
is given an input TopoJSON geometry object
.I d
and its zero-based index
.I i
in its parent collection; if the
.I expression
evaluates truthily, the geometry object is retained in the merged polygon.
.TP
.B \-\-mesh
Generate a geometry collection of lines rather than polygons.
.SH "SEE ALSO"
.BR geo2topo (1),
.BR topo2geo (1),
.BR topoquantize (1),
.BR toposimplify (1)