001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.data.gpx;
003
004import java.awt.Color;
005import java.util.Arrays;
006import java.util.Collection;
007import java.util.Collections;
008import java.util.List;
009import java.util.Map;
010import java.util.TreeMap;
011
012import org.openstreetmap.josm.data.Bounds;
013import org.openstreetmap.josm.spi.preferences.Config;
014
015/**
016 * Constants for GPX handling.
017 */
018public interface GpxConstants {
019
020    /** Prefix used for attributes when converting to OSM data */
021    String GPX_PREFIX = "gpx:";
022
023    /** GPS name of the element. This field will be transferred to and from the GPS.
024     *  GPX does not place restrictions on the length of this field or the characters contained in it.
025     *  It is up to the receiving application to validate the field before sending it to the GPS. */
026    String GPX_NAME = "name";
027
028    /** GPS element comment. Sent to GPS as comment. */
029    String GPX_CMT = "cmt";
030
031    /** Text description of the element. Holds additional information about the element intended for the user, not the GPS. */
032    String GPX_DESC = "desc";
033
034    /** Source of data. Included to give user some idea of reliability and accuracy of data. */
035    String GPX_SRC = "src";
036
037    /**
038     * Prefix used for all meta values.
039     */
040    String META_PREFIX = "meta.";
041    /**
042     * A constant for the metadata hash map: the author name of the file
043     * @see GpxData#get(String)
044     */
045    String META_AUTHOR_NAME = META_PREFIX + "author.name";
046    /**
047     * A constant for the metadata hash map: the author email of the file
048     * @see GpxData#get(String)
049     */
050    String META_AUTHOR_EMAIL = META_PREFIX + "author.email";
051    /**
052     * A constant for the metadata hash map: a link to a page about the author
053     * @see GpxData#get(String)
054     */
055    String META_AUTHOR_LINK = META_PREFIX + "author.link";
056    /**
057     * A constant for the metadata hash map: the author field for the copyright information in the gpx file
058     * @see GpxData#get(String)
059     */
060    String META_COPYRIGHT_AUTHOR = META_PREFIX + "copyright.author";
061    /**
062     * A constant for the metadata hash map: the license of the file
063     * @see GpxData#get(String)
064     */
065    String META_COPYRIGHT_LICENSE = META_PREFIX + "copyright.license";
066    /**
067     * A constant for the metadata hash map: the year of the license for the file
068     * @see GpxData#get(String)
069     */
070    String META_COPYRIGHT_YEAR = META_PREFIX + "copyright.year";
071    /**
072     * A constant for the metadata hash map: a description of the file
073     * @see GpxData#get(String)
074     */
075    String META_DESC = META_PREFIX + "desc";
076    /**
077     * A constant for the metadata hash map: the keywords of the file
078     * @see GpxData#get(String)
079     */
080    String META_KEYWORDS = META_PREFIX + "keywords";
081    /**
082     * A constant for the metadata hash map: the links. They are stored as list of {@link GpxLink} objects
083     * @see GpxData#get(String)
084     */
085    String META_LINKS = META_PREFIX + "links";
086    /**
087     * A constant for the metadata hash map: the name of the file (stored in the file, not the one on the disk)
088     * @see GpxData#get(String)
089     */
090    String META_NAME = META_PREFIX + "name";
091    /**
092     * A constant for the metadata hash map: the time as string
093     * @see GpxData#get(String)
094     */
095    String META_TIME = META_PREFIX + "time";
096    /**
097     * A constant for the metadata hash map: the bounding box. This is a {@link Bounds} object
098     * @see GpxData#getMetaBounds()
099     */
100    String META_BOUNDS = META_PREFIX + "bounds";
101
102    /**
103     * The creator element that will be written when exporting a GPX file
104     * @since 18287
105     */
106    String JOSM_CREATOR_NAME = "JOSM GPX export";
107
108    /**
109     * Namespace for the XSD
110     */
111    String XML_URI_XSD = "http://www.w3.org/2001/XMLSchema-instance";
112
113    /**
114     * Namespace for JOSM GPX extensions
115     */
116    String XML_URI_EXTENSIONS_JOSM = Config.getUrls().getXMLBase() + "/gpx-extensions-1.1";
117    /**
118     * Location of the XSD schema for JOSM GPX extensions
119     */
120    String XML_XSD_EXTENSIONS_JOSM = Config.getUrls().getXMLBase() + "/gpx-extensions-1.1.xsd";
121
122    /**
123     * Namespace for GPX drawing extensions
124     */
125    String XML_URI_EXTENSIONS_DRAWING = Config.getUrls().getXMLBase() + "/gpx-drawing-extensions-1.0";
126    /**
127     * Location of the XSD schema for GPX drawing extensions
128     */
129    String XML_XSD_EXTENSIONS_DRAWING = Config.getUrls().getXMLBase() + "/gpx-drawing-extensions-1.0.xsd";
130
131    /**
132     * Namespace for Garmin GPX extensions
133     */
134    String XML_URI_EXTENSIONS_GARMIN = "http://www.garmin.com/xmlschemas/GpxExtensions/v3";
135    /**
136     * Location of the XSD schema for GPX drawing extensions
137     */
138    String XML_XSD_EXTENSIONS_GARMIN = "http://www.garmin.com/xmlschemas/GpxExtensionsv3.xsd";
139
140    /** Elevation (in meters) of the point. */
141    String PT_ELE = "ele";
142
143    /** Creation/modification timestamp for the point.
144     *  Date and time in are in Coordinated Universal Time (UTC), not local time!
145     *  Conforms to ISO 8601 specification for date/time representation.
146     *  Fractional seconds are allowed for millisecond timing in tracklogs. */
147    String PT_TIME = "time";
148
149    /** Magnetic variation (in degrees) at the point. 0.0 <= value < 360.0 */
150    String PT_MAGVAR = "magvar";
151
152    /** Height, in meters, of geoid (mean sea level) above WGS-84 earth ellipsoid. (NMEA GGA message) */
153    String PT_GEOIDHEIGHT = "geoidheight";
154
155    /** Text of GPS symbol name. For interchange with other programs, use the exact spelling of the symbol on the GPS, if known. */
156    String PT_SYM = "sym";
157
158    /** Type (textual classification) of element. */
159    String PT_TYPE = "type";
160
161    /** Type of GPS fix. none means GPS had no fix. Value comes from list: {'none'|'2d'|'3d'|'dgps'|'pps'} */
162    String PT_FIX = "fix";
163
164    /** Number of satellites used to calculate the GPS fix. (not number of satellites in view). */
165    String PT_SAT = "sat";
166
167    /** Horizontal dilution of precision. */
168    String PT_HDOP = "hdop";
169
170    /** Vertical dilution of precision. */
171    String PT_VDOP = "vdop";
172
173    /** Position dilution of precision. */
174    String PT_PDOP = "pdop";
175
176    /** Number of seconds since last DGPS update. */
177    String PT_AGEOFDGPSDATA = "ageofdgpsdata";
178
179    /** Represents a differential GPS station. 0 <= value <= 1023 */
180    String PT_DGPSID = "dgpsid";
181
182    /**
183     * Ordered list of all possible waypoint keys.
184     */
185    List<String> WPT_KEYS = Collections.unmodifiableList(Arrays.asList(PT_ELE, PT_TIME, PT_MAGVAR, PT_GEOIDHEIGHT,
186            GPX_NAME, GPX_CMT, GPX_DESC, GPX_SRC, META_LINKS, PT_SYM, PT_TYPE,
187            PT_FIX, PT_SAT, PT_HDOP, PT_VDOP, PT_PDOP, PT_AGEOFDGPSDATA, PT_DGPSID));
188
189    /**
190     * Ordered list of all possible route and track keys.
191     */
192    List<String> RTE_TRK_KEYS = Collections.unmodifiableList(Arrays.asList(
193            GPX_NAME, GPX_CMT, GPX_DESC, GPX_SRC, META_LINKS, "number", PT_TYPE));
194
195    /**
196     * Map with all supported Garmin colors
197     */
198    Map<String, Color> GARMIN_COLORS = getGarminColors();
199
200    /**
201     * Helper method for {@link #GARMIN_COLORS}
202     * @return Map with all supported Garmin colors
203     */
204    static Map<String, Color> getGarminColors() {
205        TreeMap<String, Color> m = new TreeMap<>(String.CASE_INSENSITIVE_ORDER);
206        m.put("Black", Color.BLACK);
207        m.put("DarkRed", new Color(139, 0, 0));
208        m.put("DarkGreen", new Color(0, 100, 0));
209        m.put("DarkYellow", new Color(255, 170, 0));
210        m.put("DarkBlue", new Color(0, 0, 139));
211        m.put("DarkMagenta", new Color(139, 0, 139));
212        m.put("DarkCyan", new Color(0, 139, 139));
213        m.put("LightGray", Color.LIGHT_GRAY);
214        m.put("DarkGray", Color.DARK_GRAY);
215        m.put("Red", Color.RED);
216        m.put("Green", Color.GREEN);
217        m.put("Yellow", Color.YELLOW);
218        m.put("Blue", Color.BLUE);
219        m.put("Magenta", Color.MAGENTA);
220        m.put("Cyan", Color.CYAN);
221        m.put("White", Color.WHITE);
222        m.put("Transparent", new Color(0, 0, 0, 255));
223        return Collections.unmodifiableMap(m);
224    }
225
226    /**
227     * Enum with color formats that can be written by JOSM
228     */
229    enum ColorFormat {
230        /** Drawing extension format */
231        GPXD,
232        /** Garmin track extension format */
233        GPXX
234    }
235
236    /**
237     * Map with all supported extension abbreviations for easier readability in OSM layers
238     */
239    Map<String, String> EXTENSION_ABBREVIATIONS = getExtensionAbbreviations();
240
241    /**
242     * Helper method for {@link #EXTENSION_ABBREVIATIONS}
243     * @return Map with all supported extension abbreviations
244     */
245    static Map<String, String> getExtensionAbbreviations() {
246        TreeMap<String, String> m = new TreeMap<>(String.CASE_INSENSITIVE_ORDER);
247        m.put("gpx:extension:gpxx:TrackExtension:DisplayColor", "gpxx:DisplayColor");
248        m.put("gpx:extension:gpxd:color", "gpxd:color");
249        return m;
250    }
251
252    /**
253     * Possible fix values. NMEA 0183 Version 4.00
254     */
255    Collection<String> FIX_VALUES = Collections.unmodifiableList(
256            Arrays.asList("none", "2d", "3d", "dgps", "pps", "rtk", "float rtk", "estimated", "manual", "simulated"));
257
258    /**
259     * The flag which indicates the solution quality.<ul>
260     * <li>1 : Fixed, solution by carrier‐based relative positioning and the integer ambiguity is properly resolved.</li>
261     * <li>2 : Float, solution by carrier‐based relative positioning but the integer ambiguity is not resolved.</li>
262     * <li>3 : Reserved</li>
263     * <li>4 : DGPS, solution by code‐based DGPS solutions or single point positioning with SBAS corrections</li>
264     * <li>5 : Single, solution by single point positioning</li></ul>
265     * @since 15247
266     */
267    String RTKLIB_Q = "Q";
268    /** N (north) component of the standard deviations in m. */
269    String RTKLIB_SDN = "sdn";
270    /** E (east) component of the standard deviations in m. */
271    String RTKLIB_SDE = "sde";
272    /** U (up) component of the standard deviations in m. */
273    String RTKLIB_SDU = "sdu";
274    /**
275     * The absolute value of sdne means square root of the absolute value of NE component of the estimated covariance matrix.
276     * The sign represents the sign of the covariance. */
277    String RTKLIB_SDNE = "sdne";
278    /**
279     * The absolute value of sdeu means square root of the absolute value of EU component of the estimated covariance matrix.
280     * The sign represents the sign of the covariance. */
281    String RTKLIB_SDEU = "sdeu";
282    /**
283     * The absolute value of sdun means square root of the absolute value of UN component of the estimated covariance matrix.
284     * The sign represents the sign of the covariance. */
285    String RTKLIB_SDUN = "sdun";
286    /** The time difference between the observation data epochs of the rover receiver and the base station in second. */
287    String RTKLIB_AGE = "age";
288    /**
289     * The ratio factor of ʺratio‐testʺ for standard integer ambiguity validation strategy.
290     * The value means the ratio of the squared sum of the residuals with the second best integer vector to with the best integer vector. */
291    String RTKLIB_RATIO = "ratio";
292}