001 /*
002 * Java GPX Library (jpx-3.1.0).
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 /**
018 * <em>JPX</em> is a library for creating, reading and writing
019 * <a href="https://en.wikipedia.org/wiki/Global_Positioning_System">GPS</a>
020 * data in <a href="https://en.wikipedia.org/wiki/GPS_Exchange_Format">GPX</a>
021 * format. It is a <em>full</em> implementation of version
022 * <a href="http://www.topografix.com/GPX/1/1/">1.1</a> and version
023 * <a href="http://www.topografix.com/gpx_manual.as">1.0</a> of the GPX format.
024 * The data classes are completely immutable and allows a functional programming
025 * style. It is also possible to convert the location information into strings
026 * which are compatible to the <a href="http://en.wikipedia.org/wiki/ISO_6709">
027 * ISO 6709</a> standard.
028 *
029 * <p>
030 * <em><b>Examples:</b></em>
031 * <p>
032 * <b>Creating a GPX object with one track-segment and 3 track-points</b>
033 * <pre>{@code
034 * final GPX gpx = GPX.builder()
035 * .addTrack(track -> track
036 * .addSegment(segment -> segment
037 * .addPoint(p -> p.lat(48.20100).lon(16.31651).ele(283))
038 * .addPoint(p -> p.lat(48.20112).lon(16.31639).ele(278))
039 * .addPoint(p -> p.lat(48.20126).lon(16.31601).ele(274))))
040 * .build();
041 * }</pre>
042 *
043 * <b>Writing a GPX file</b>
044 * <pre>{@code
045 * final var indent = new GPX.Writer.Indent(" ");
046 * GPX.Writer.of(indent).write(gpx, Path.of("points.gpx"));
047 * }</pre>
048 *
049 * This will produce the following output.
050 * <pre>{@code
051 * <gpx version="1.1" creator="JPX - https://github.com/jenetics/jpx" xmlns="http://www.topografix.com/GPX/1/1">
052 * <trk>
053 * <trkseg>
054 * <trkpt lat="48.201" lon="16.31651">
055 * <ele>283</ele>
056 * </trkpt>
057 * <trkpt lat="48.20112" lon="16.31639">
058 * <ele>278</ele>
059 * </trkpt>
060 * <trkpt lat="48.20126" lon="16.31601">
061 * <ele>274</ele>
062 * </trkpt>
063 * </trkseg>
064 * </trk>
065 * </gpx>
066 * }</pre>
067 *
068 * <b>Reading a GPX file</b>
069 * <pre>{@code
070 * final GPX gpx = GPX.read("points.xml");
071 * }</pre>
072 *
073 * <b>Reading erroneous GPX files</b>
074 * <pre>{@code
075 * final GPX gpx = GPX.Reader.of(GPX.Reader.Mode.LENIENT).read("track.xml");
076 * }</pre>
077 *
078 * This allows to read otherwise invalid GPX files, like
079 * <pre>{@code
080 * <?xml version="1.0" encoding="UTF-8"?>
081 * <gpx version="1.1" creator="GPSBabel - http://www.gpsbabel.org" xmlns="http://www.topografix.com/GPX/1/1">
082 * <metadata>
083 * <time>2019-12-31T21:36:04.134Z</time>
084 * <bounds minlat="48.175186667" minlon="16.299580000" maxlat="48.199555000" maxlon="16.416933333"/>
085 * </metadata>
086 * <trk>
087 * <trkseg>
088 * <trkpt lat="48.184298333" lon="16.299580000">
089 * <ele>0.000</ele>
090 * <time>2011-03-20T09:47:16Z</time>
091 * <geoidheight>43.5</geoidheight>
092 * <fix>2d</fix>
093 * <sat>3</sat>
094 * <hdop>4.200000</hdop>
095 * <vdop>1.000000</vdop>
096 * <pdop>4.300000</pdop>
097 * </trkpt>
098 * <trkpt lat="48.175186667" lon="16.303916667">
099 * <ele>0.000</ele>
100 * <time>2011-03-20T09:51:31Z</time>
101 * <geoidheight>43.5</geoidheight>
102 * <fix>2d</fix>
103 * <sat>3</sat>
104 * <hdop>16.600000</hdop>
105 * <vdop>0.900000</vdop>
106 * <pdop>16.600000</pdop>
107 * </trkpt>
108 * </trkseg>
109 * </trk>
110 * </gpx>
111 * }</pre>
112 *
113 * which is read as (if you write it again)
114 * <pre>{@code
115 * <?xml version="1.0" encoding="UTF-8"?>
116 * <gpx version="1.1" creator="GPSBabel - http://www.gpsbabel.org" xmlns="http://www.topografix.com/GPX/1/1">
117 * <metadata>
118 * <time>2019-12-31T21:36:04.134Z</time>
119 * <bounds minlat="48.175187" minlon="16.29958" maxlat="48.199555" maxlon="16.416933"></bounds>
120 * </metadata>
121 * <trk>
122 * <trkseg>
123 * <trkpt lat="48.184298" lon="16.29958">
124 * <ele>0</ele>
125 * <time>2011-03-20T09:47:16Z</time>
126 * <geoidheight>43.5</geoidheight>
127 * <fix>2d</fix>
128 * <sat>3</sat>
129 * <hdop>4.2</hdop>
130 * <vdop>1</vdop>
131 * <pdop>4.3</pdop>
132 * </trkpt>
133 * <trkpt lat="48.175187" lon="16.303917">
134 * <ele>0</ele>
135 * <time>2011-03-20T09:51:31Z</time>
136 * <geoidheight>43.5</geoidheight>
137 * <fix>2d</fix>
138 * <sat>3</sat>
139 * <hdop>16.6</hdop>
140 * <vdop>0.9</vdop>
141 * <pdop>16.6</pdop>
142 * </trkpt>
143 * </trkseg>
144 * </trk>
145 * </gpx>
146 * }</pre>
147 *
148 * <b>Converting a GPX object to an XML {@link org.w3c.dom.Document}</b>
149 * <pre>{@code
150 * final GPX gpx = ...;
151 *
152 * final Document doc = XMLProvider.provider()
153 * .documentBuilderFactory()
154 * .newDocumentBuilder()
155 * .newDocument();
156 *
157 * // The GPX data are written to the empty `doc` object.
158 * GPX.Writer.DEFAULT.write(gpx, new DOMResult(doc));
159 * }</pre>
160 */
161 module io.jenetics.jpx {
162 requires transitive java.xml;
163
164 exports io.jenetics.jpx;
165 exports io.jenetics.jpx.format;
166 exports io.jenetics.jpx.geom;
167
168 uses io.jenetics.jpx.XMLProvider;
169 }
|