How locationtech/jts works
1. Repository shape
This is a multi-module Maven Java project centered on the JTS Topology Suite. The root aggregates reusable geometry libraries, user-facing tools, integration adapters, examples, and a large test corpus. The main architectural boundary is between the immutable-ish geometry core and everything that consumes or visualizes it.
2. Core geometry engine
modules/core is the primary subsystem and contains the fundamental geometry model: Coordinate, Geometry, Point, LineString, Polygon, GeometryFactory, PrecisionModel, and related sequence/collection types. Most other modules depend on this layer. It is the canonical source of geometry state passed through the rest of the system.
3. Algorithm and operation layers
The core module is organized around geometry-processing subsystems: algorithm for low-level numeric/topological routines, operation for higher-level tasks like buffer, overlay, union, distance, relate, validation, polygonize, and line merge, plus simplify, triangulate, linearref, coverage, and precision. The data flow is typically Geometry in → noding/indexing/graph construction → topological computation → new Geometry out.
4. Spatial indexing and robustness infrastructure
A major architectural concern in JTS is robustness under floating-point error. That shows up in dedicated packages for precision reduction, common-bits handling, snap rounding, and robust overlay/relate variants. The indexing packages (quadtree, strtree, kdtree, hprtree, interval trees, sweep line) support performance-critical operations and are embedded beneath many algorithms rather than exposed as standalone application logic.
5. Geometry graph / noding / planar graph boundary
Several internal subsystems model geometry as graphs of edges, nodes, and intersections (geomgraph, planargraph, edgegraph, noding). These are the connective tissue for overlay, relate, buffer, polygonization, and validation. Architecturally, they transform raw coordinate sequences into topological structures that downstream operations can reason about safely.
6. I/O and interchange adapters
modules/core contains classic WKT/WKB/GML/KML readers and writers. modules/io/common adds GeoJSON and TWKB support, modules/io/ora supports Oracle geometries, and modules/io/sde supports SDE input. These modules form the ingest/egress boundary: external text/binary spatial formats are normalized into core Geometry objects, then serialized back out after processing.
7. TestBuilder application stack
modules/app is the desktop application layer, centered on the TestBuilder GUI. Its internal structure is explicit: model classes hold editable layers/test cases, controllers coordinate commands and results, UI panels and dialogs present geometry, renderers paint layers, and tool classes handle interaction. The app is a visualization and editing shell around the same core geometry engine.
8. TestBuilder data flow
In the GUI, geometry enters from WKT/WKB/shapefile/import dialogs, is stored in the model, edited via tools, and rendered through the Swing-based view layer. User actions invoke geometry functions, which are registered/reflected through function registries and invocation wrappers, then results are routed to result panels, inspectors, and export writers such as HTML, SVG, PNG, XML, or Java test cases.
9. Test runner subsystem
modules/tests is a separate test-execution framework used by the XML-based geometry test suites. It parses test definitions, loads geometry operations/functions, executes them against inputs, and compares results with specialized matchers. This module is the bridge between static test data and the library’s operation APIs, and it also supports CLI execution and reporting.
10. Example and lab code
modules/example is a documentation-oriented sample application layer showing how to use core APIs, IO readers/writers, prepared geometry, linear referencing, and operation classes. modules/lab contains experimental or exploratory algorithms such as overlay-area variants, edge-ray methods, medial axis, and custom union strategies. These are clearly separated from the stable core APIs and should be treated as incubating extensions.
11. Shared command-line and utility code
There are small command-line entry points and utilities in the app and test modules, including JTSOp/TestRunner-related commands and general-purpose file, command, and stream helpers. These are thin orchestration layers: they parse inputs, call the geometry engine, and format results, but do not own geometry logic themselves.
12. Build, quality, and release infrastructure
The repo uses Maven across modules and GitHub Actions for CI. Build tooling includes checkstyle/PMD configuration, release documentation, and multiple shell/batch launchers for the GUI and command-line tools. The architecture is therefore not just library-centric; it also includes a repeatable validation pipeline with broad test coverage and packaged desktop/CLI tooling.
Main entry points: geom Geometry model · operation Operations · pom.xml Modules POM · testbuilder TestBuilder
Components 25
Repo
Multi-module Maven geometry toolkit centered on JTS core
- Root POM · Aggregates the multi-module build
pom.xml - Modules POM · Common module aggregation for the subprojects
modules/pom.xml
Core engine
Geometry model, algorithms, indexes, and operations
- Geometry model · Coordinate, Geometry, factory, precision, and sequence types
modules/core/src/main/java/org/locationtech/jts/geom - Operations · Buffer, overlay, union, relate, validation, simplify, linearref, coverage
modules/core/src/main/java/org/locationtech/jts/operation - Algorithms · Numeric and topological routines used by higher-level operations
modules/core/src/main/java/org/locationtech/jts/algorithm - Noding & graphs · Segment noding and graph structures for overlay and relate
modules/core/src/main/java/org/locationtech/jts/noding - Spatial indexes · Quadtree, STRtree, kdtree, interval trees, and sweep-line indexes
modules/core/src/main/java/org/locationtech/jts/index - Precision tools · Common bits, precision reduction, and enhanced precision support
modules/core/src/main/java/org/locationtech/jts/precision - Core IO · Canonical text and binary geometry readers and writers
modules/core/src/main/java/org/locationtech/jts/io - Prepared geom · Prepared geometry support for faster repeated spatial predicates
modules/core/src/main/java/org/locationtech/jts/geom/prep
IO adapters
Format readers and writers around core Geometry
- Common IO · GeoJSON and TWKB adapters built on core geometry
modules/io/common/src/main/java/org/locationtech/jts/io - Oracle IO · Oracle geometry reader and writer integration
modules/io/ora/src/main/java/org/locationtech/jts/io/oracle - SDE IO · SDE input adapter into core Geometry
modules/io/sde/src/main/java/org/locationtech/jts/io/sde
Desktop app
TestBuilder GUI, command tools, and rendering
- TestBuilder · Swing-based geometry inspection, editing, and visualization shell
modules/app/src/main/java/org/locationtech/jtstest/testbuilder - CLI tools · JTSOp and related command-line entry points
modules/app/src/main/java/org/locationtech/jtstest/cmd - Function registry · Reflective geometry function wrappers used by tools and GUI
modules/app/src/main/java/org/locationtech/jtstest/geomfunction - Rendering UI · Layer rendering, styles, tools, and view management
modules/app/src/main/java/org/locationtech/jtstest/testbuilder/ui - App model · Layers, test cases, result containers, and undo state
modules/app/src/main/java/org/locationtech/jtstest/testbuilder/model
Test runner
XML-driven geometry test execution and matching
- TestRunner · XML-driven geometry test execution and reporting
modules/tests/src/main/java/org/locationtech/jtstest/testrunner - Geom ops · Operation wrappers, matchers, and function loading for tests
modules/tests/src/main/java/org/locationtech/jtstest/geomop - XML suites · Large geometry test data sets for correctness and robustness
modules/tests/src/test/resources/testxml
Examples & lab
Samples and experimental geometry work
Build & CI
Maven, quality gates, and release automation
- Build tools · Checkstyle, PMD, suppression, and shared build resources
build-tools/src/main/resources/jts - GitHub Actions · Automated build and test workflow
.github/workflows/build-and-test.yml
Connections 39
- Root POM → Modules POM: aggregates · Root build includes the module aggregator
- Modules POM → Geometry model: builds · Core module is the main dependency base
- Modules POM → Operations: builds · Operation layer is packaged from core
- Modules POM → Core IO: builds · Core IO is part of the main library
- Modules POM → Common IO: builds · Additional interchange adapters
- Modules POM → TestBuilder: builds · Desktop TestBuilder application
- Modules POM → TestRunner: builds · Standalone test execution framework
- Modules POM → Examples: builds · Example module compiles against core APIs
- Modules POM → Lab code: builds · Experimental module remains separate
- Geometry model → Algorithms: uses · Geometry model underpins algorithms
- Geometry model → Noding & graphs: feeds · Coordinates and segments are noded for topology
- Geometry model → Spatial indexes: queries · Geometry operations rely on spatial indexing
- Geometry model → Precision tools: stabilizes · Precision tools protect geometry computations
- Geometry model → Prepared geom: accelerates · Prepared geometries optimize repeated predicates
- Operations → Noding & graphs: depends on · Overlay, relate, and polygonization build topological graphs
- Operations → Spatial indexes: depends on · Performance-critical operations use spatial indexes
- Operations → Precision tools: depends on · Robust variants reduce floating-point error
- Operations → Geometry model: returns · Operations produce new Geometry objects
- Algorithms → Spatial indexes: accelerates · Some algorithms use indexed search
- Core IO → Geometry model: serializes · Reads and writes normalized geometry objects
- Common IO → Geometry model: extends · GeoJSON and TWKB adapters target core geometry
- Oracle IO → Geometry model: bridges · Oracle geometry conversion boundary
- SDE IO → Geometry model: bridges · SDE input is normalized into core geometry
- TestBuilder → App model: uses · GUI state is held in the application model
- TestBuilder → Rendering UI: renders via · Swing views and tools paint geometry state
- TestBuilder → Function registry: invokes · Registered geometry functions drive interactive actions
- CLI tools → Core IO: parses · CLI tools ingest and emit geometry text/binary
- CLI tools → Operations: executes · Command-line operations call into geometry algorithms
- Function registry → Operations: wraps · Function registry exposes operation APIs
- Rendering UI → Geometry model: draws · Rendering works from core geometry objects
- TestRunner → Geom ops: loads · Runner uses operation adapters and matchers
- Geom ops → Operations: executes · Test operations call the geometry engine
- TestRunner → XML suites: drives · XML suites provide inputs and expected outputs
- Examples → Geometry model: demonstrates · Examples show core model usage
- Examples → Operations: demonstrates · Examples exercise common operations
- Lab code → Operations: experiments with · Lab code explores alternative algorithms
- Build tools → Root POM: supports · Shared build rules apply across modules
- GitHub Actions → Build tools: enforces · CI runs quality checks and tests
- GitHub Actions → TestRunner: runs · Automation executes the test harness