source: josm/trunk/src/org/openstreetmap/josm/data/Bounds.java@ 17534

Last change on this file since 17534 was 16664, checked in by simon04, 4 years ago

Improve Javadoc
  • Property svn:eol-style set to native
File size: 19.9 KB
Line 
1// License: GPL. For details, see LICENSE file.
2package org.openstreetmap.josm.data;
3
4import static org.openstreetmap.josm.tools.I18n.tr;
5
6import java.awt.geom.Rectangle2D;
7import java.text.DecimalFormat;
8import java.text.MessageFormat;
9import java.util.Objects;
10
11import org.openstreetmap.josm.data.coor.ILatLon;
12import org.openstreetmap.josm.data.coor.LatLon;
13import org.openstreetmap.josm.data.osm.BBox;
14import org.openstreetmap.josm.tools.CheckParameterUtil;
15
16/**
17 * This is a simple data class for "rectangular" areas of the world, given in
18 * lat/lon min/max values. The values are {@linkplain LatLon#roundToOsmPrecision(double) rounded to server precision}
19 *
20 * @author imi
21 *
22 * @see BBox to represent invalid areas.
23 */
24public class Bounds {
25 /**
26 * The minimum and maximum coordinates.
27 */
28 private double minLat, minLon, maxLat, maxLon;
29
30 /**
31 * Gets the point that has both the minimal lat and lon coordinate
32 * @return The point
33 */
34 public LatLon getMin() {
35 return new LatLon(minLat, minLon);
36 }
37
38 /**
39 * Returns min latitude of bounds. Efficient shortcut for {@code getMin().lat()}.
40 *
41 * @return min latitude of bounds.
42 * @since 6203
43 */
44 public double getMinLat() {
45 return minLat;
46 }
47
48 /**
49 * Returns min longitude of bounds. Efficient shortcut for {@code getMin().lon()}.
50 *
51 * @return min longitude of bounds.
52 * @since 6203
53 */
54 public double getMinLon() {
55 return minLon;
56 }
57
58 /**
59 * Gets the point that has both the maximum lat and lon coordinate
60 * @return The point
61 */
62 public LatLon getMax() {
63 return new LatLon(maxLat, maxLon);
64 }
65
66 /**
67 * Returns max latitude of bounds. Efficient shortcut for {@code getMax().lat()}.
68 *
69 * @return max latitude of bounds.
70 * @since 6203
71 */
72 public double getMaxLat() {
73 return maxLat;
74 }
75
76 /**
77 * Returns max longitude of bounds. Efficient shortcut for {@code getMax().lon()}.
78 *
79 * @return max longitude of bounds.
80 * @since 6203
81 */
82 public double getMaxLon() {
83 return maxLon;
84 }
85
86 /**
87 * The method used by the {@link Bounds#Bounds(String, String, ParseMethod)} constructor
88 */
89 public enum ParseMethod {
90 /**
91 * Order: minlat, minlon, maxlat, maxlon
92 */
93 MINLAT_MINLON_MAXLAT_MAXLON,
94 /**
95 * Order: left, bottom, right, top
96 */
97 LEFT_BOTTOM_RIGHT_TOP
98 }
99
100 /**
101 * Construct bounds out of two points. Coords will be rounded.
102 * @param min min lat/lon
103 * @param max max lat/lon
104 */
105 public Bounds(LatLon min, LatLon max) {
106 this(min.lat(), min.lon(), max.lat(), max.lon());
107 }
108
109 /**
110 * Constructs bounds out of two points.
111 * @param min min lat/lon
112 * @param max max lat/lon
113 * @param roundToOsmPrecision defines if lat/lon will be rounded
114 */
115 public Bounds(LatLon min, LatLon max, boolean roundToOsmPrecision) {
116 this(min.lat(), min.lon(), max.lat(), max.lon(), roundToOsmPrecision);
117 }
118
119 /**
120 * Constructs bounds out a single point. Coords will be rounded.
121 * @param b lat/lon
122 */
123 public Bounds(LatLon b) {
124 this(b, true);
125 }
126
127 /**
128 * Single point Bounds defined by lat/lon {@code b}.
129 * Coordinates will be rounded to osm precision if {@code roundToOsmPrecision} is true.
130 *
131 * @param b lat/lon of given point.
132 * @param roundToOsmPrecision defines if lat/lon will be rounded.
133 */
134 public Bounds(LatLon b, boolean roundToOsmPrecision) {
135 this(b.lat(), b.lon(), roundToOsmPrecision);
136 }
137
138 /**
139 * Single point Bounds defined by point [lat,lon].
140 * Coordinates will be rounded to osm precision if {@code roundToOsmPrecision} is true.
141 *
142 * @param lat latitude of given point.
143 * @param lon longitude of given point.
144 * @param roundToOsmPrecision defines if lat/lon will be rounded.
145 * @since 6203
146 */
147 public Bounds(double lat, double lon, boolean roundToOsmPrecision) {
148 // Do not call this(b, b) to avoid GPX performance issue (see #7028) until roundToOsmPrecision() is improved
149 if (roundToOsmPrecision) {
150 this.minLat = LatLon.roundToOsmPrecision(lat);
151 this.minLon = LatLon.roundToOsmPrecision(lon);
152 } else {
153 this.minLat = lat;
154 this.minLon = lon;
155 }
156 this.maxLat = this.minLat;
157 this.maxLon = this.minLon;
158 }
159
160 /**
161 * Constructs bounds out of two points. Coords will be rounded.
162 * @param minLat min lat
163 * @param minLon min lon
164 * @param maxLat max lat
165 * @param maxLon max lon
166 */
167 public Bounds(double minLat, double minLon, double maxLat, double maxLon) {
168 this(minLat, minLon, maxLat, maxLon, true);
169 }
170
171 /**
172 * Constructs bounds out of two points.
173 * @param minLat min lat
174 * @param minLon min lon
175 * @param maxLat max lat
176 * @param maxLon max lon
177 * @param roundToOsmPrecision defines if lat/lon will be rounded
178 */
179 public Bounds(double minLat, double minLon, double maxLat, double maxLon, boolean roundToOsmPrecision) {
180 if (roundToOsmPrecision) {
181 this.minLat = LatLon.roundToOsmPrecision(minLat);
182 this.minLon = LatLon.roundToOsmPrecision(minLon);
183 this.maxLat = LatLon.roundToOsmPrecision(maxLat);
184 this.maxLon = LatLon.roundToOsmPrecision(maxLon);
185 } else {
186 this.minLat = minLat;
187 this.minLon = minLon;
188 this.maxLat = maxLat;
189 this.maxLon = maxLon;
190 }
191 }
192
193 /**
194 * Constructs bounds out of two points. Coords will be rounded.
195 * @param coords exactly 4 values: min lat, min lon, max lat, max lon
196 * @throws IllegalArgumentException if coords does not contain 4 double values
197 */
198 public Bounds(double... coords) {
199 this(coords, true);
200 }
201
202 /**
203 * Constructs bounds out of two points.
204 * @param coords exactly 4 values: min lat, min lon, max lat, max lon
205 * @param roundToOsmPrecision defines if lat/lon will be rounded
206 * @throws IllegalArgumentException if coords does not contain 4 double values
207 */
208 public Bounds(double[] coords, boolean roundToOsmPrecision) {
209 CheckParameterUtil.ensureParameterNotNull(coords, "coords");
210 if (coords.length != 4)
211 throw new IllegalArgumentException(MessageFormat.format("Expected array of length 4, got {0}", coords.length));
212 if (roundToOsmPrecision) {
213 this.minLat = LatLon.roundToOsmPrecision(coords[0]);
214 this.minLon = LatLon.roundToOsmPrecision(coords[1]);
215 this.maxLat = LatLon.roundToOsmPrecision(coords[2]);
216 this.maxLon = LatLon.roundToOsmPrecision(coords[3]);
217 } else {
218 this.minLat = coords[0];
219 this.minLon = coords[1];
220 this.maxLat = coords[2];
221 this.maxLon = coords[3];
222 }
223 }
224
225 /**
226 * Parse the bounds in order {@link ParseMethod#MINLAT_MINLON_MAXLAT_MAXLON}
227 * @param asString The string
228 * @param separator The separation regex
229 */
230 public Bounds(String asString, String separator) {
231 this(asString, separator, ParseMethod.MINLAT_MINLON_MAXLAT_MAXLON);
232 }
233
234 /**
235 * Parse the bounds from a given string and round to OSM precision
236 * @param asString The string
237 * @param separator The separation regex
238 * @param parseMethod The order of the numbers
239 */
240 public Bounds(String asString, String separator, ParseMethod parseMethod) {
241 this(asString, separator, parseMethod, true);
242 }
243
244 /**
245 * Parse the bounds from a given string
246 * @param asString The string
247 * @param separator The separation regex
248 * @param parseMethod The order of the numbers
249 * @param roundToOsmPrecision Whether to round to OSM precision
250 */
251 public Bounds(String asString, String separator, ParseMethod parseMethod, boolean roundToOsmPrecision) {
252 CheckParameterUtil.ensureParameterNotNull(asString, "asString");
253 String[] components = asString.split(separator, -1);
254 if (components.length != 4)
255 throw new IllegalArgumentException(
256 MessageFormat.format("Exactly four doubles expected in string, got {0}: {1}", components.length, asString));
257 double[] values = new double[4];
258 for (int i = 0; i < 4; i++) {
259 try {
260 values[i] = Double.parseDouble(components[i]);
261 } catch (NumberFormatException e) {
262 throw new IllegalArgumentException(MessageFormat.format("Illegal double value ''{0}''", components[i]), e);
263 }
264 }
265
266 switch (parseMethod) {
267 case LEFT_BOTTOM_RIGHT_TOP:
268 this.minLat = initLat(values[1], roundToOsmPrecision);
269 this.minLon = initLon(values[0], roundToOsmPrecision);
270 this.maxLat = initLat(values[3], roundToOsmPrecision);
271 this.maxLon = initLon(values[2], roundToOsmPrecision);
272 break;
273 case MINLAT_MINLON_MAXLAT_MAXLON:
274 default:
275 this.minLat = initLat(values[0], roundToOsmPrecision);
276 this.minLon = initLon(values[1], roundToOsmPrecision);
277 this.maxLat = initLat(values[2], roundToOsmPrecision);
278 this.maxLon = initLon(values[3], roundToOsmPrecision);
279 }
280 }
281
282 protected static double initLat(double value, boolean roundToOsmPrecision) {
283 if (!LatLon.isValidLat(value))
284 throw new IllegalArgumentException(tr("Illegal latitude value ''{0}''", value));
285 return roundToOsmPrecision ? LatLon.roundToOsmPrecision(value) : value;
286 }
287
288 protected static double initLon(double value, boolean roundToOsmPrecision) {
289 if (!LatLon.isValidLon(value))
290 throw new IllegalArgumentException(tr("Illegal longitude value ''{0}''", value));
291 return roundToOsmPrecision ? LatLon.roundToOsmPrecision(value) : value;
292 }
293
294 /**
295 * Creates new {@code Bounds} from an existing one.
296 * @param other The bounds to copy
297 */
298 public Bounds(final Bounds other) {
299 this(other.minLat, other.minLon, other.maxLat, other.maxLon);
300 }
301
302 /**
303 * Creates new {@code Bounds} from a rectangle.
304 * @param rect The rectangle
305 */
306 public Bounds(Rectangle2D rect) {
307 this(rect.getMinY(), rect.getMinX(), rect.getMaxY(), rect.getMaxX());
308 }
309
310 /**
311 * Creates new bounds around a coordinate pair <code>center</code>. The
312 * new bounds shall have an extension in latitude direction of <code>latExtent</code>,
313 * and in longitude direction of <code>lonExtent</code>.
314 *
315 * @param center the center coordinate pair. Must not be null.
316 * @param latExtent the latitude extent. &gt; 0 required.
317 * @param lonExtent the longitude extent. &gt; 0 required.
318 * @throws IllegalArgumentException if center is null
319 * @throws IllegalArgumentException if latExtent &lt;= 0
320 * @throws IllegalArgumentException if lonExtent &lt;= 0
321 */
322 public Bounds(LatLon center, double latExtent, double lonExtent) {
323 CheckParameterUtil.ensureParameterNotNull(center, "center");
324 if (latExtent <= 0.0)
325 throw new IllegalArgumentException(MessageFormat.format("Parameter ''{0}'' > 0.0 expected, got {1}", "latExtent", latExtent));
326 if (lonExtent <= 0.0)
327 throw new IllegalArgumentException(MessageFormat.format("Parameter ''{0}'' > 0.0 expected, got {1}", "lonExtent", lonExtent));
328
329 this.minLat = LatLon.roundToOsmPrecision(LatLon.toIntervalLat(center.lat() - latExtent / 2));
330 this.minLon = LatLon.roundToOsmPrecision(LatLon.toIntervalLon(center.lon() - lonExtent / 2));
331 this.maxLat = LatLon.roundToOsmPrecision(LatLon.toIntervalLat(center.lat() + latExtent / 2));
332 this.maxLon = LatLon.roundToOsmPrecision(LatLon.toIntervalLon(center.lon() + lonExtent / 2));
333 }
334
335 /**
336 * Creates BBox with same coordinates.
337 *
338 * @return BBox with same coordinates.
339 * @since 6203
340 */
341 public BBox toBBox() {
342 return new BBox(minLon, minLat, maxLon, maxLat);
343 }
344
345 @Override
346 public String toString() {
347 return "Bounds["+minLat+','+minLon+','+maxLat+','+maxLon+']';
348 }
349
350 /**
351 * Converts this bounds to a human readable short string
352 * @param format The number format to use
353 * @return The string
354 */
355 public String toShortString(DecimalFormat format) {
356 return format.format(minLat) + ' '
357 + format.format(minLon) + " / "
358 + format.format(maxLat) + ' '
359 + format.format(maxLon);
360 }
361
362 /**
363 * Returns center of the bounding box.
364 * @return Center of the bounding box.
365 */
366 public LatLon getCenter() {
367 if (crosses180thMeridian()) {
368 double lat = (minLat + maxLat) / 2;
369 double lon = (minLon + maxLon - 360.0) / 2;
370 if (lon < -180.0) {
371 lon += 360.0;
372 }
373 return new LatLon(lat, lon);
374 } else {
375 return new LatLon((minLat + maxLat) / 2, (minLon + maxLon) / 2);
376 }
377 }
378
379 /**
380 * Extend the bounds if necessary to include the given point.
381 * @param ll The point to include into these bounds
382 */
383 public void extend(LatLon ll) {
384 extend(ll.lat(), ll.lon());
385 }
386
387 /**
388 * Extend the bounds if necessary to include the given point [lat,lon].
389 * Good to use if you know coordinates to avoid creation of LatLon object.
390 * @param lat Latitude of point to include into these bounds
391 * @param lon Longitude of point to include into these bounds
392 * @since 6203
393 */
394 public void extend(final double lat, final double lon) {
395 if (lat < minLat) {
396 minLat = LatLon.roundToOsmPrecision(lat);
397 }
398 if (lat > maxLat) {
399 maxLat = LatLon.roundToOsmPrecision(lat);
400 }
401 if (crosses180thMeridian()) {
402 if (lon > maxLon && lon < minLon) {
403 if (Math.abs(lon - minLon) <= Math.abs(lon - maxLon)) {
404 minLon = LatLon.roundToOsmPrecision(lon);
405 } else {
406 maxLon = LatLon.roundToOsmPrecision(lon);
407 }
408 }
409 } else {
410 if (lon < minLon) {
411 minLon = LatLon.roundToOsmPrecision(lon);
412 }
413 if (lon > maxLon) {
414 maxLon = LatLon.roundToOsmPrecision(lon);
415 }
416 }
417 }
418
419 /**
420 * Extends this bounds to enclose an other bounding box
421 * @param b The other bounds to enclose
422 */
423 public void extend(Bounds b) {
424 extend(b.minLat, b.minLon);
425 extend(b.maxLat, b.maxLon);
426 }
427
428 /**
429 * Determines if the given point {@code ll} is within these bounds.
430 * <p>
431 * Points with unknown coordinates are always outside the coordinates.
432 * @param ll The lat/lon to check
433 * @return {@code true} if {@code ll} is within these bounds, {@code false} otherwise
434 */
435 public boolean contains(LatLon ll) {
436 // binary compatibility
437 return contains((ILatLon) ll);
438 }
439
440 /**
441 * Determines if the given point {@code ll} is within these bounds.
442 * <p>
443 * Points with unknown coordinates are always outside the coordinates.
444 * @param ll The lat/lon to check
445 * @return {@code true} if {@code ll} is within these bounds, {@code false} otherwise
446 * @since 12161
447 */
448 public boolean contains(ILatLon ll) {
449 if (!ll.isLatLonKnown()) {
450 return false;
451 }
452 if (ll.lat() < minLat || ll.lat() > maxLat)
453 return false;
454 if (crosses180thMeridian()) {
455 if (ll.lon() > maxLon && ll.lon() < minLon)
456 return false;
457 } else {
458 if (ll.lon() < minLon || ll.lon() > maxLon)
459 return false;
460 }
461 return true;
462 }
463
464 private static boolean intersectsLonCrossing(Bounds crossing, Bounds notCrossing) {
465 return notCrossing.minLon <= crossing.maxLon || notCrossing.maxLon >= crossing.minLon;
466 }
467
468 /**
469 * The two bounds intersect? Compared to java Shape.intersects, if does not use
470 * the interior but the closure. ("&gt;=" instead of "&gt;")
471 * @param b other bounds
472 * @return {@code true} if the two bounds intersect
473 */
474 public boolean intersects(Bounds b) {
475 if (b.maxLat < minLat || b.minLat > maxLat)
476 return false;
477
478 if (crosses180thMeridian() && !b.crosses180thMeridian()) {
479 return intersectsLonCrossing(this, b);
480 } else if (!crosses180thMeridian() && b.crosses180thMeridian()) {
481 return intersectsLonCrossing(b, this);
482 } else if (crosses180thMeridian() && b.crosses180thMeridian()) {
483 return true;
484 } else {
485 return b.maxLon >= minLon && b.minLon <= maxLon;
486 }
487 }
488
489 /**
490 * Determines if this Bounds object crosses the 180th Meridian.
491 * See http://wiki.openstreetmap.org/wiki/180th_meridian
492 * @return true if this Bounds object crosses the 180th Meridian.
493 */
494 public boolean crosses180thMeridian() {
495 return this.minLon > this.maxLon;
496 }
497
498 /**
499 * Converts the lat/lon bounding box to an object of type Rectangle2D.Double
500 * @return the bounding box to Rectangle2D.Double
501 */
502 public Rectangle2D.Double asRect() {
503 return new Rectangle2D.Double(minLon, minLat, getWidth(), getHeight());
504 }
505
506 /**
507 * Returns the bounds width.
508 * @return the bounds width
509 * @since 14521
510 */
511 public double getHeight() {
512 return maxLat-minLat;
513 }
514
515 /**
516 * Returns the bounds width.
517 * @return the bounds width
518 * @since 14521
519 */
520 public double getWidth() {
521 return maxLon-minLon + (crosses180thMeridian() ? 360.0 : 0.0);
522 }
523
524 /**
525 * Gets the area of this bounds (in lat/lon space)
526 * @return The area
527 */
528 public double getArea() {
529 return getWidth() * getHeight();
530 }
531
532 /**
533 * Encodes this as a string so that it may be parsed using the {@link ParseMethod#MINLAT_MINLON_MAXLAT_MAXLON} order
534 * @param separator The separator
535 * @return The string encoded bounds
536 */
537 public String encodeAsString(String separator) {
538 return new StringBuilder()
539 .append(minLat).append(separator).append(minLon).append(separator)
540 .append(maxLat).append(separator).append(maxLon).toString();
541 }
542
543 /**
544 * <p>Replies true, if this bounds are <em>collapsed</em>, i.e. if the min
545 * and the max corner are equal.</p>
546 *
547 * @return true, if this bounds are <em>collapsed</em>
548 */
549 public boolean isCollapsed() {
550 return Double.doubleToLongBits(minLat) == Double.doubleToLongBits(maxLat)
551 && Double.doubleToLongBits(minLon) == Double.doubleToLongBits(maxLon);
552 }
553
554 /**
555 * Determines if these bounds are out of the world.
556 * @return true if lat outside of range [-90,90] or lon outside of range [-180,180]
557 */
558 public boolean isOutOfTheWorld() {
559 return
560 !LatLon.isValidLat(minLat) ||
561 !LatLon.isValidLat(maxLat) ||
562 !LatLon.isValidLon(minLon) ||
563 !LatLon.isValidLon(maxLon);
564 }
565
566 /**
567 * Clamp the bounds to be inside the world.
568 */
569 public void normalize() {
570 minLat = LatLon.toIntervalLat(minLat);
571 maxLat = LatLon.toIntervalLat(maxLat);
572 minLon = LatLon.toIntervalLon(minLon);
573 maxLon = LatLon.toIntervalLon(maxLon);
574 }
575
576 @Override
577 public int hashCode() {
578 return Objects.hash(minLat, minLon, maxLat, maxLon);
579 }
580
581 @Override
582 public boolean equals(Object obj) {
583 if (this == obj) return true;
584 if (obj == null || getClass() != obj.getClass()) return false;
585 Bounds bounds = (Bounds) obj;
586 return Double.compare(bounds.minLat, minLat) == 0 &&
587 Double.compare(bounds.minLon, minLon) == 0 &&
588 Double.compare(bounds.maxLat, maxLat) == 0 &&
589 Double.compare(bounds.maxLon, maxLon) == 0;
590 }
591}
Note: See TracBrowser for help on using the repository browser.