MapThing

A Processing library for reading and displaying geographic data in map-based sketches. MapThing loads ESRI shapefiles, CSV/TSV, and GPX files, remaps their geographic coordinates onto the Processing sketch canvas, and provides tools for thematic mapping and feature filtering.

Originally developed by Jon Reades.

Note: This is a fork updated for compatibility with Processing 4 (Java 17). The original library used GeoTools 2.7-M3 which is incompatible with Java 17's module system. This version upgrades to GeoTools 28.2 and JTS 1.19.0.

---

Installation

The version of MapThing currently available in the Processing library manager in version 1.4 which is no longer compatible. For the present please install MapThing manually.

Manual install

1. Download the latest MapThing.zip from the Releases page and unzip it.

2. Move the MapThing folder into the libraries folder of your Processing sketchbook.

   Default sketchbook locations:

   • Windows: Documents\Processing\libraries\
   • macOS: ~/Documents/Processing/libraries/
   • Linux: ~/sketchbook/libraries/

   To check your sketchbook location, open Processing and go to File > Preferences.

3. Restart Processing. The library will appear under Sketch > Import Library > Contributed Libraries.

4. Import it in your sketch:

   import com.reades.mapthing.*;

---

Classes

BoundingBox

Defines the geographic envelope of the sketch — the area of the world you want to display. Constructed with a projection (EPSG code) and North/East/South/West extents. All other classes use a BoundingBox to map geographic coordinates onto the Processing canvas.

// Irish Transverse Mercator (EPSG:2175), extents in metres
BoundingBox envelope = new BoundingBox(2175, 736875f, 719875f, 731875f, 711875f);

// WGS84 lat/lon
BoundingBox envelope = new BoundingBox(53.4f, -6.1f, 53.3f, -6.3f);

Key methods:

• heightFromWidth(int w) / widthFromHeight(int h) — calculate canvas dimensions preserving the geographic aspect ratio
• getProjection(), getNorth(), getSouth(), getEast(), getWest()

---

Polygons

Reads and displays polygon features from a shapefile.

Polygons regions = new Polygons(envelope, dataPath("regions.shp"));

// In draw():
regions.project(this);                    // outline only (uses current stroke/fill)
regions.projectValues(this, 0f, 100f);    // choropleth fill using value field

Key methods:

• setValueField(String fieldName) — column to use for thematic colouring
• setColourScale(int low, int high, int steps) — define the colour ramp
• setColourScale(int low, int mid, int high, int steps) — diverging colour ramp
• setLocalSimplificationThreshold(double d) — simplify geometry (units match the shapefile's CRS)
• getMultipleFeaturesByPattern(String field, String value) — filter features by a LIKE pattern
• getMultipleFeaturesByValue(String field, double min) — filter features above a numeric threshold
• getCentroids() — return polygon centroids as a feature collection
• project(PApplet a, PGraphics p) — draw into an offscreen buffer
• projectValues(PApplet a, PGraphics p, float min, float max) — choropleth fill into an offscreen buffer

---

Lines

Reads and displays line features from a shapefile or CSV/TSV.

Lines roads = new Lines(envelope, dataPath("roads.shp"));

// In draw():
roads.project(this);
roads.projectValues(this, 0f, 50f);    // colour by value field

Key methods:

• setValueField(String fieldName)
• setColourScale(int low, int high, int steps)
• setLocalSimplificationThreshold(double d) — Douglas-Peucker simplification
• getCoordinates(PApplet a) — returns ArrayList<Node[]> of transformed coordinates
• reverse() — reverse line direction
• project(PApplet a, PGraphics p)

---

Points

Reads and displays point features from a shapefile, CSV, TSV, or GPX file.

Points cities = new Points(envelope, dataPath("cities.tsv"));

// In draw():
cities.project(this, 6f, 6f);                        // ellipse at each point
cities.projectValues(this, 6f, 6f, 0f, 1000000f);    // colour by value
cities.projectAreas(this, 20f, 1000000f);             // scale size by value
cities.label(this);                                    // draw text labels
cities.project(this, markerImage, 16f, 16f);           // image marker

Key methods:

• setValueField(String fieldName) / setLabelField(String fieldName)
• setColourScale(int low, int high, int steps)
• dedupe(boolean useFirst) — remove duplicate coordinates
• labelOffset(int x, int y) — offset text labels from the point
• getCoordinates(PApplet a) — returns ArrayList<Node> of transformed points

---

Node

Internal data class representing a single point that has been transformed into sketch coordinates. Holds x, y, z position, a numeric value, and a name string. Returned by getCoordinates() on all geometry classes.

Link

Represents a weighted, directed or undirected connection between two Node objects. Useful for network visualisation.

---

Common Features (all geometry classes)

Method	Description
setValueField(String)	Name of the attribute column to use for values
setLabelField(String)	Name of the attribute column to use for labels
setColourScale(low, high, steps)	Two-colour ramp
setColourScale(low, mid, high, steps)	Three-colour diverging ramp
getMultipleFeaturesByPattern(field, pattern)	SQL LIKE filter — returns a FeatureCollection suitable for passing to a new geometry constructor
getMultipleFeaturesByValue(field, min)	Numeric threshold filter
getFeatures()	Raw FeatureIterator for direct GeoTools access
getBounds()	Returns the ReferencedEnvelope of the data

---

Supported File Formats

Format	Extension	Points	Lines	Polygons
ESRI Shapefile	.shp	Yes	Yes	Yes
Comma-separated	.csv	Yes	Yes	—
Tab-separated	.tsv	Yes	Yes	—
GPS Exchange	.gpx	Yes	Yes	—

For CSV/TSV files, coordinate columns are detected automatically by name. Recognised column names:

• X / Longitude / Easting: x, x1, easting, lon, long, longitude
• Y / Latitude / Northing: y, y1, northing, lat, latitude

---

Building from Source

Requirements: Java 17, the Gradle wrapper is included (no separate Gradle install needed).

# Compile and run tests
./gradlew build

# Install directly into your local Processing sketchbook
./gradlew deployToProcessingSketchbook

# Build a distributable ZIP and PDEX for release
./gradlew buildReleaseArtifacts

deployToProcessingSketchbook auto-detects the sketchbook location on macOS, Windows, and Linux. If it picks the wrong path, set sketchbookLocation manually at the top of build.gradle.kts.

After updating a dependency version, regenerate the lock files and verification checksums:

./gradlew dependencies --write-locks
./gradlew --write-verification-metadata sha256 dependencies

---

Dependencies

All runtime dependencies are resolved automatically by Gradle and bundled into the release artifact. They do not need to be installed separately.

GeoTools 28.2

Geospatial data handling — shapefile reading, coordinate reference systems, feature filtering.

Module	Purpose
gt-shapefile	ESRI shapefile reader
gt-cql	CQL/OGC filter expressions
gt-epsg-hsql	EPSG coordinate reference system database

Supporting Libraries

Library	Purpose
JTS Topology Suite 1.19.0	Geometry operations and spatial algorithms
HSQLDB 2.7.1	Embedded database for the EPSG CRS registry
JDOM 1.1.3	XML parsing for GPX support
GeographicLib-Java 1.49	Geodesic calculations

---

Licence

This library is free software released under the GNU Lesser General Public Licence v2.1.