JPX is a Java library for creating, reading and writing GPS data in GPX format. It is a full implementation of version 1.1 and version 1.0 of the GPX format. The data classes are completely immutable and allows a functional programming style. They are working also nicely with the Java Stream API. It is also possible to convert the location information into strings which are compatible to the ISO 6709 standard.
Besides the basic functionality of reading and writing GPX files, the library also allows manipulating the read GPX object in a functional way.
The JPX library needs no external dependencies. It only needs Java 17 to compile and run. It also runs and compiles with Java 21 and Java 23.
For building the JPX library, you have to check out the master branch from GitHub.
$ git clone https://github.com/jenetics/jpx.git
Executing the tests:
$ cd jpx
$ ./gradlew test
Building the library:
$ ./gradlew jar
final GPX gpx = GPX.builder()
.addTrack(track -> track
.addSegment(segment -> segment
.addPoint(p -> p.lat(48.20100).lon(16.31651).ele(283))
.addPoint(p -> p.lat(48.20112).lon(16.31639).ele(278))
.addPoint(p -> p.lat(48.20126).lon(16.31601).ele(274))))
.build();Writing GPX object to a file
GPX.write(gpx, Path.of("track.gpx"));GPX output
<gpx version="1.1" creator="JPX - https://github.com/jenetics/jpx" xmlns="http://www.topografix.com/GPX/1/1">
<trk>
<trkseg>
<trkpt lat="48.201" lon="16.31651">
<ele>283</ele>
</trkpt>
<trkpt lat="48.20112" lon="16.31639">
<ele>278</ele>
</trkpt>
<trkpt lat="48.20126" lon="16.31601">
<ele>274</ele>
</trkpt>
</trkseg>
</trk>
</gpx>This example writes a given GPX object to a file, reads it again and prints the WayPoints of all tracks and all track-segments to the console.
GPX.write(gpx, Path.of("track.gpx"));
GPX.read("gpx.xml").tracks()
.flatMap(Track::segments)
.flatMap(TrackSegment::points)
.forEach(System.out::println);Console output
$ [lat=48.201, lon=16.31651, ele=283]
$ [lat=48.20112, lon=16.31639, ele=278]
$ [lat=48.20126, lon=16.31601, ele=274]
The library is also able to read arbitrary GPX extensions.
<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="JPX - Java GPX library" xmlns="http://www.topografix.com/GPX/1/1">
...
<extensions>
<gpxdata:lap xmlns:gpxdata="http://www.cluetrust.com/XML/GPXDATA/1/0">
<gpxdata:index>1</gpxdata:index>
<gpxdata:startPoint lat="51.219983" lon="6.765224"/>
<gpxdata:endPoint lat="51.220137" lon="6.765098" />
</gpxdata:lap>
</extensions>
</gpx>
The extensions are available via a org.w3c.dom.Document object, with an extensions root element.
final Optional<Document> extensions = gpx.getExtensions();final GPX gpx = ...;
final Document doc = XMLProvider.provider()
.documentBuilderFactory()
.newDocumentBuilder()
.newDocument();
// The GPX data are written to the empty `doc` object.
GPX.Writer.DEFAULT.write(gpx, new DOMResult(doc));By default, JPX is reading and writing the GPX files in version 1.1. But it is possible to read and write GPX files in version 1.0 as well.
// Reading GPX 1.0 file.
final GPX gpx10 = GPX.reader(GPX.Version.V10).read("track-v10.gpx");
// Changing GPX version to 1.1.
final GPX gpx11 = gpx10.toBuilder()
.version(GPX.Version.V11)
.build();
// Writing GPX to file.
GPX.write(gpx11, Path.of("track-v11.gpx"));With the LocationFormatter class it is possible to create ISO 6709 compatible strings.
final Point p = WayPoint.of(...);
final Location loc = Location.of(p);
final LocationFormatter format = LocationFormatter.ISO_HUMAN_LONG;
System.out.println(format.format(loc));The printed location will look like this
24°59'15.486"N 65°14'03.390"W 65.23m
It is also possible to define your own formatter from a given pattern string,
final LocationFormatter format =
LocationFormatter.ofPattern("DD°MMSS dd°mmss");which leads to the following output
24°5915 65°1403
This string can then also be parsed to a location.
final Location location = format.parse("24°5915 65°1403");final Point start = WayPoint.of(47.2692124, 11.4041024);
final Point end = WayPoint.of(47.3502, 11.70584);
final Length distance = Geoid.WGS84.distance(start, end);
System.out.println(distance);Console output
$ 24528.356073554987 mCalculate the path length of the first track-segment.
final Length length = gpx.tracks()
.flatMap(Track::segments)
.findFirst()
.map(TrackSegment::points).orElse(Stream.empty())
.collect(Geoid.WGS84.toPathLength());The following example filters empty tracks and track-segments from an existing GPX object.
final GPX gpx = GPX.read("track.gpx");
// Filtering empty tracks.
final GPX gpx1 = gpx.toBuilder()
.trackFilter()
.filter(Track::nonEmpty)
.build()
.build();
// Filtering empty track-segments.
final GPX gpx2 = gpx.toBuilder()
.trackFilter()
.map(track -> track.toBuilder()
.filter(TrackSegment::nonEmpty)
.build())
.build()
.build();
// Filtering empty tracks and track-segments.
final GPX gpx3 = gpx.toBuilder()
.trackFilter()
.map(track -> track.toBuilder()
.filter(TrackSegment::nonEmpty)
.build())
.filter(Track::nonEmpty)
.build()
.build();Fixing the time of all track way-points by adding one hour.
final GPX gpx = GPX.read("track.gpx");
final GPX gpx1 = gpx.toBuilder()
.trackFilter()
.map(track -> track.toBuilder()
.map(segment -> segment.toBuilder()
.map(wp -> wp.toBuilder()
.time(wp.getTime()
.map(t -> t.plusHours(1))
.orElse(null))
.build())
.build())
.build())
.build()
.build();Doing the same only for the GPX way-points.
final GPX gpx = GPX.read("track.gpx");
final GPX gpx1 = gpx.toBuilder()
.wayPointFilter()
.map(wp -> wp.toBuilder()
.time(wp.getTime()
.map(t -> t.plusHours(1))
.orElse(null))
.build())
.build()
.build();The JPX library uses the XML classes available in the Java java.xml module. This API is highly configurable, and it is possible to replace the underlying implementation. Especially for Android, using different XML implementation is a necessity. JPX uses three factory classes for reading/writing GPX files:
XMLInputFactory: This class is needed for reading GPX files.XMLOutputFactory: This class is needed for writing GPX files.DocumentBuilderFactory: This class is used for creating XML-documents for the GPXextensionsdata.
You can change the used classes by implementing and registering a different XMLProvider class. The following code show how to change the configuration of the DocumentBuilderFactory class.
package org.acme;
final class ValidatingDocumentBuilder extends XMLProvider {
@Override
public DocumentBuilderFactory documentBuilderFactory() {
final DocumentBuilderFactory factory =
DocumentBuilderFactory.newInstance();
factory.setValidating(true);
factory.setNamespaceAware(true);
return factory;
}
}And remember to create a META-INF/services/io.jenetics.jpx.XMLProvider file with the following content:
org.acme.NonValidatingDocumentBuilder
The library is licensed under the Apache License, Version 2.0.
Copyright 2016-2024 Franz Wilhelmstötter
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
- #170: GPX files with invalid version number are now readable in LENIENT mode.
final GPX gpx;
try (InputStream in = new FileInputStream(resource)) {
gpx = GPX.Reader.of(Mode.LENIENT).read(in);
}- #167: Fixing a test case for Windows.
- #162: Elevation serialization for values > 1000m is incompatible with deserialization.
- #125: Breaking change - Use
Instantinstead ofZonedDateTimeforPoint.timeproperty. - #148: Breaking change - Update to Java17.
- #155: Improved
GPX.ReaderandGPX.Writerclasses. - #158: Add XML
Documentreader/writer methods.
final GPX gpx = ...;
final Document doc = XMLProvider.provider()
.documentBuilderFactory()
.newDocumentBuilder()
.newDocument();
// The GPX data are written to the empty `doc` object.
GPX.Writer.DEFAULT.write(gpx, new DOMResult(doc));