From 569db8c666f608dae15d1ce9f76c47ff1ffc58c7 Mon Sep 17 00:00:00 2001
From: Luc Maisonobe <luc@orekit.org>
Date: Sat, 11 Dec 2021 10:51:52 +0100
Subject: [PATCH] Javadoc.

---
 src/main/java/org/orekit/rugged/raster/Tile.java | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/main/java/org/orekit/rugged/raster/Tile.java b/src/main/java/org/orekit/rugged/raster/Tile.java
index ccdb66dc..d8950677 100644
--- a/src/main/java/org/orekit/rugged/raster/Tile.java
+++ b/src/main/java/org/orekit/rugged/raster/Tile.java
@@ -256,7 +256,19 @@ public interface Tile extends UpdatableTile {
     double interpolateElevation(double latitude, double longitude);
 
     /** Find the intersection of a line-of-sight and a Digital Elevation Model cell.
-     * @param p point on the line
+     * <p>
+     * Beware that for continuity reasons, the point argument in {@code cellIntersection} is normalized
+     * with respect to other points used by the caller. This implies that the longitude may be
+     * outside of the [-Ï€ ; +Ï€] interval (or the [0 ; 2Ï€] interval, depending on the DEM). In particular,
+     * when a Line Of Sight crosses the antimeridian at  ±π longitude, the library may call the
+     * {@code cellIntersection} method with a point having a longitude of -π-ε to ensure this continuity.
+     * As tiles are stored with longitude clipped to a some DEM specific interval (either  [-Ï€ ; +Ï€] or [0 ; 2Ï€]),
+     * implementations MUST take care to clip the input point back to the tile interval using
+     * {@link org.hipparchus.util.MathUtils#normalizeAngle(double, double) MathUtils.normalizeAngle(p.getLongitude(),
+     * someLongitudeWithinTheTile)}. The output point normalization should also be made consistent with
+     * the current tile.
+     * </p>
+     * @param p point on the line (beware its longitude is <em>not</em> normalized with respect to tile)
      * @param los line-of-sight, in the topocentric frame (East, North, Zenith) of the point,
      * scaled to match radians in the horizontal plane and meters along the vertical axis
      * @param latitudeIndex latitude index of the Digital Elevation Model cell
-- 
GitLab