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     * Namespace for the XSD
104     */
105    String XML_URI_XSD = "http://www.w3.org/2001/XMLSchema-instance";
106
107    /**
108     * Namespace for JOSM GPX extensions
109     */
110    String XML_URI_EXTENSIONS_JOSM = Config.getUrls().getXMLBase() + "/gpx-extensions-1.1";
111    /**
112     * Location of the XSD schema for JOSM GPX extensions
113     */
114    String XML_XSD_EXTENSIONS_JOSM = Config.getUrls().getXMLBase() + "/gpx-extensions-1.1.xsd";
115
116    /**
117     * Namespace for GPX drawing extensions
118     */
119    String XML_URI_EXTENSIONS_DRAWING = Config.getUrls().getXMLBase() + "/gpx-drawing-extensions-1.0";
120    /**
121     * Location of the XSD schema for GPX drawing extensions
122     */
123    String XML_XSD_EXTENSIONS_DRAWING = Config.getUrls().getXMLBase() + "/gpx-drawing-extensions-1.0.xsd";
124
125    /**
126     * Namespace for Garmin GPX extensions
127     */
128    String XML_URI_EXTENSIONS_GARMIN = "http://www.garmin.com/xmlschemas/GpxExtensions/v3";
129    /**
130     * Location of the XSD schema for GPX drawing extensions
131     */
132    String XML_XSD_EXTENSIONS_GARMIN = "http://www.garmin.com/xmlschemas/GpxExtensionsv3.xsd";
133
134    /** Elevation (in meters) of the point. */
135    String PT_ELE = "ele";
136
137    /** Creation/modification timestamp for the point.
138     *  Date and time in are in Univeral Coordinated Time (UTC), not local time!
139     *  Conforms to ISO 8601 specification for date/time representation.
140     *  Fractional seconds are allowed for millisecond timing in tracklogs. */
141    String PT_TIME = "time";
142
143    /** Magnetic variation (in degrees) at the point. 0.0 <= value < 360.0 */
144    String PT_MAGVAR = "magvar";
145
146    /** Height, in meters, of geoid (mean sea level) above WGS-84 earth ellipsoid. (NMEA GGA message) */
147    String PT_GEOIDHEIGHT = "geoidheight";
148
149    /** Text of GPS symbol name. For interchange with other programs, use the exact spelling of the symbol on the GPS, if known. */
150    String PT_SYM = "sym";
151
152    /** Type (textual classification) of element. */
153    String PT_TYPE = "type";
154
155    /** Type of GPS fix. none means GPS had no fix. Value comes from list: {'none'|'2d'|'3d'|'dgps'|'pps'} */
156    String PT_FIX = "fix";
157
158    /** Number of satellites used to calculate the GPS fix. (not number of satellites in view). */
159    String PT_SAT = "sat";
160
161    /** Horizontal dilution of precision. */
162    String PT_HDOP = "hdop";
163
164    /** Vertical dilution of precision. */
165    String PT_VDOP = "vdop";
166
167    /** Position dilution of precision. */
168    String PT_PDOP = "pdop";
169
170    /** Number of seconds since last DGPS update. */
171    String PT_AGEOFDGPSDATA = "ageofdgpsdata";
172
173    /** Represents a differential GPS station. 0 <= value <= 1023 */
174    String PT_DGPSID = "dgpsid";
175
176    /**
177     * Ordered list of all possible waypoint keys.
178     */
179    List<String> WPT_KEYS = Collections.unmodifiableList(Arrays.asList(PT_ELE, PT_TIME, PT_MAGVAR, PT_GEOIDHEIGHT,
180            GPX_NAME, GPX_CMT, GPX_DESC, GPX_SRC, META_LINKS, PT_SYM, PT_TYPE,
181            PT_FIX, PT_SAT, PT_HDOP, PT_VDOP, PT_PDOP, PT_AGEOFDGPSDATA, PT_DGPSID));
182
183    /**
184     * Ordered list of all possible route and track keys.
185     */
186    List<String> RTE_TRK_KEYS = Collections.unmodifiableList(Arrays.asList(
187            GPX_NAME, GPX_CMT, GPX_DESC, GPX_SRC, META_LINKS, "number", PT_TYPE));
188
189    /**
190     * Map with all supported Garmin colors
191     */
192    Map<String, Color> GARMIN_COLORS = getGarminColors();
193
194    /**
195     * Helper method for {@link #GARMIN_COLORS}
196     * @return Map with all supported Garmin colors
197     */
198    static Map<String, Color> getGarminColors() {
199        TreeMap<String, Color> m = new TreeMap<>(String.CASE_INSENSITIVE_ORDER);
200        m.put("Black", Color.BLACK);
201        m.put("DarkRed", new Color(139, 0, 0));
202        m.put("DarkGreen", new Color(0, 100, 0));
203        m.put("DarkYellow", new Color(255, 170, 0));
204        m.put("DarkBlue", new Color(0, 0, 139));
205        m.put("DarkMagenta", new Color(139, 0, 139));
206        m.put("DarkCyan", new Color(0, 139, 139));
207        m.put("LightGray", Color.LIGHT_GRAY);
208        m.put("DarkGray", Color.DARK_GRAY);
209        m.put("Red", Color.RED);
210        m.put("Green", Color.GREEN);
211        m.put("Yellow", Color.YELLOW);
212        m.put("Blue", Color.BLUE);
213        m.put("Magenta", Color.MAGENTA);
214        m.put("Cyan", Color.CYAN);
215        m.put("White", Color.WHITE);
216        m.put("Transparent", new Color(0, 0, 0, 255));
217        return Collections.unmodifiableMap(m);
218    }
219
220    /**
221     * Enum with color formats that can be written by JOSM
222     */
223    enum ColorFormat {
224        /** Drawing extension format */
225        GPXD,
226        /** Garmin track extension format */
227        GPXX
228    }
229
230    /**
231     * Map with all supported extension abbreviations for easier readability in OSM layers
232     */
233    Map<String, String> EXTENSION_ABBREVIATIONS = getExtensionAbbreviations();
234
235    /**
236     * Helper method for {@link #EXTENSION_ABBREVIATIONS}
237     * @return Map with all supported extension abbreviations
238     */
239    static Map<String, String> getExtensionAbbreviations() {
240        TreeMap<String, String> m = new TreeMap<>(String.CASE_INSENSITIVE_ORDER);
241        m.put("gpx:extension:gpxx:TrackExtensions:DisplayColor", "gpxx:DisplayColor");
242        m.put("gpx:extension:gpxd:color", "gpxd:color");
243        return m;
244    }
245
246    /**
247     * Possible fix values. NMEA 0183 Version 4.00
248     */
249    Collection<String> FIX_VALUES = Collections.unmodifiableList(
250            Arrays.asList("none", "2d", "3d", "dgps", "pps", "rtk", "float rtk", "estimated", "manual", "simulated"));
251
252    /**
253     * The flag which indicates the solution quality.<ul>
254     * <li>1 : Fixed, solution by carrier‐based relative positioning and the integer ambiguity is properly resolved.</li>
255     * <li>2 : Float, solution by carrier‐based relative positioning but the integer ambiguity is not resolved.</li>
256     * <li>3 : Reserved</li>
257     * <li>4 : DGPS, solution by code‐based DGPS solutions or single point positioning with SBAS corrections</li>
258     * <li>5 : Single, solution by single point positioning</li></ul>
259     * @since 15247
260     */
261    String RTKLIB_Q = "Q";
262    /** N (north) component of the standard deviations in m. */
263    String RTKLIB_SDN = "sdn";
264    /** E (east) component of the standard deviations in m. */
265    String RTKLIB_SDE = "sde";
266    /** U (up) component of the standard deviations in m. */
267    String RTKLIB_SDU = "sdu";
268    /**
269     * The absolute value of sdne means square root of the absolute value of NE component of the estimated covariance matrix.
270     * The sign represents the sign of the covariance. */
271    String RTKLIB_SDNE = "sdne";
272    /**
273     * The absolute value of sdeu means square root of the absolute value of EU component of the estimated covariance matrix.
274     * The sign represents the sign of the covariance. */
275    String RTKLIB_SDEU = "sdeu";
276    /**
277     * The absolute value of sdun means square root of the absolute value of UN component of the estimated covariance matrix.
278     * The sign represents the sign of the covariance. */
279    String RTKLIB_SDUN = "sdun";
280    /** The time difference between the observation data epochs of the rover receiver and the base station in second. */
281    String RTKLIB_AGE = "age";
282    /**
283     * The ratio factor of ʺratio‐testʺ for standard integer ambiguity validation strategy.
284     * The value means the ratio of the squared sum of the residuals with the second best integer vector to with the best integer vector. */
285    String RTKLIB_RATIO = "ratio";
286}