refactor: make some logic and properties public

This refactoring allows helix-toolkit library to generate 3D models from HGT files using SRTM library

Author: alex-valchuk

src/SRTM/EmptySRTMDataCell.cs

@@ -31,11 +31,31 @@ public EmptySRTMDataCell(string filepath)
 
         public int Longitude { get; private set; }
 
+        public byte[] HgtData => Array.Empty<byte>();
+
+        public int PointsPerCell => -1;
+
+        public int VerticalPointsPerCell => -1;
+
+        public double PointHeightInMeters => -1;
+
+        public double PointWidthInMeters => -1;
+
+        public int GetBytePositionByCoordinate(double latitude, double longitude)
+        {
+            return 0;
+        }
+
         public int? GetElevation(double latitude, double longitude)
         {
             return null;
         }
 
+        public int? GetElevation(int bytesPos)
+        {
+            return null;
+        }
+
         public double? GetElevationBilinear(double latitude, double longitude)
         {
             return null;

src/SRTM/ISRTMData.cs

@@ -44,7 +44,15 @@ public interface ISRTMData
         /// Represents errors that occur during application execution.
         /// </exception>
         int? GetElevation(double latitude, double longitude);
-        
+
+        /// <summary>
+        /// Method responsible for identifying the correct data cell and either retrieving it from cache ir downloading it from source.
+        /// </summary>
+        /// <param name="latitude"></param>
+        /// <param name="longitude"></param>
+        /// <returns>Elevation data cell. Must be an instance of the <see cref="SRTM.ISRTMDataCell"/> class.</returns>
+        ISRTMDataCell GetDataCell(double latitude, double longitude);
+
         /// <summary>
         /// Gets the elevation. Data is smoothed using bilinear interpolation.
         /// </summary>

src/SRTM/ISRTMDataCell.cs

@@ -6,8 +6,28 @@ public interface ISRTMDataCell
 
         int Longitude { get; }
 
+        byte[] HgtData { get; }
+
+        int PointsPerCell { get; }
+
+        /// <summary>
+        /// Gets the number of vertical points per cell.
+        /// Useful for custom data cells that must have square shape.
+        /// On majority of earth places it is feasible only when the number of horizontal and vertical points are different.
+        /// It's because the size of vertical arc-second is constant while the size of horizontal one is different on different latitudes.
+        /// </summary>
+        int VerticalPointsPerCell { get; }
+
+        double PointHeightInMeters { get; }
+
+        double PointWidthInMeters { get; }
+
         int? GetElevation(double latitude, double longitude);
 
         double? GetElevationBilinear(double latitude, double longitude);
+
+        int GetBytePositionByCoordinate(double latitude, double longitude);
+
+        int? GetElevation(int bytesPos);
     }
 }

src/SRTM/SRTM.csproj

@@ -6,11 +6,12 @@
     <ApplicationIcon />
     <StartupObject />
     <LangVersion>latest</LangVersion>
+    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
   </PropertyGroup>
 
   <PropertyGroup>
     <DefineConstants>LIBLOG_PORTABLE</DefineConstants>
-    <Version>0.0.7</Version>
+    <Version>0.0.8</Version>
     <Authors>Ben Abelshausen</Authors>
     <Company>Itinero</Company>
     <Description>A library to read SRTM data, loads missing files on-the-fly.</Description>

src/SRTM/SRTMData.cs

@@ -104,7 +104,7 @@ public SRTMData(string dataDirectory, Func<(string path, string name), bool> get
         /// <value>
         /// The SRTM data cells.
         /// </value>
-        private List<ISRTMDataCell> DataCells { get; set; }
+        protected List<ISRTMDataCell> DataCells { get; private set; }
 
         #region Public methods
 
@@ -168,7 +168,7 @@ public void Unload()
         /// <param name="latitude"></param>
         /// <param name="longitude"></param>
         /// <returns>Elevation data cell. Must be an instance of the <see cref="SRTM.ISRTMDataCell"/> class.</returns>
-        private ISRTMDataCell GetDataCell(double latitude, double longitude)
+        public ISRTMDataCell GetDataCell(double latitude, double longitude)
         {
             int cellLatitude = (int)Math.Floor(Math.Abs(latitude));
             if (latitude < 0)
@@ -228,16 +228,9 @@ private ISRTMDataCell GetDataCell(double latitude, double longitude)
                     }
                 }
             }
-            
-            if (File.Exists(filePath))
-            {
-                dataCell = new SRTMDataCell(filePath);
-            }
-            else if(File.Exists(zipFilePath))
-            {
-                dataCell = new SRTMDataCell(zipFilePath);
-            }
-            else
+
+            if (!TryReadExistingFile(filePath, out dataCell) &&
+                !TryReadExistingFile(zipFilePath, out dataCell))
             {
                 if (count < 0)
                 {
@@ -259,6 +252,27 @@ private ISRTMDataCell GetDataCell(double latitude, double longitude)
 
             return dataCell;
         }
+
+        protected bool TryReadExistingFile(string filePath, out ISRTMDataCell dataCell)
+        {
+            dataCell = null;
+
+            try
+            {
+                if (File.Exists(filePath))
+                {
+                    dataCell = new SRTMDataCell(filePath);
+                    return true;
+                }
+            }
+            catch
+            {
+                // probably the file is corrupted.
+                File.Delete(filePath);
+            }
+
+            return false;
+        }
 
         #endregion
     }

src/SRTM/SRTMDataCell.cs

@@ -42,6 +42,8 @@ public class SRTMDataCell : ISRTMDataCell
     {
         #region Lifecycle
 
+        private static readonly double _oneArcSecondAtEquator = 30.87f;
+
         /// <summary>
         /// Initializes a new instance of the <see cref="SRTM.SRTMDataCell"/> class.
         /// </summary>
@@ -95,17 +97,30 @@ public SRTMDataCell(string filepath)
 
             switch (HgtData.Length)
             {
+                // https://www.esri.com/news/arcuser/0400/wdside.html#:~:text=At%20the%20equator%2C%20an%20arc,101.27%20feet%20or%2030.87%20meters).
+                // At the equator, an arc-second of longitude approximately equals an arc-second of latitude, which is 1 / 60th of a nautical mile(or 101.27 feet or 30.87 meters).
+                // Arc-seconds of latitude remain nearly constant, while arc-seconds of longitude decrease in a trigonometric cosine-based fashion as one moves toward the earth's poles.
+                // E.g. at 49 degrees north latitude, along the northern boundary of the Concrete sheet, an arc-second of longitude equals 30.87 meters * 0.6561 (cos 49) or 20.250 meters. 
                 case 1201 * 1201 * 2: // SRTM-3
                     PointsPerCell = 1201;
+                    VerticalPointsPerCell = 1201;
+                    PointHeightInMeters = _oneArcSecondAtEquator * 3; // 3 arc-seconds
+                    PointWidthInMeters = _oneArcSecondAtEquator * 3 * Math.Cos(ConvertToRadians(Latitude));
                     break;
                 case 3601 * 3601 * 2: // SRTM-1
                     PointsPerCell = 3601;
+                    VerticalPointsPerCell = 3601;
+                    PointHeightInMeters = _oneArcSecondAtEquator; // 1 arc-second
+                    PointWidthInMeters = _oneArcSecondAtEquator * Math.Cos(ConvertToRadians(Latitude));
                     break;
                 default:
                     throw new ArgumentException("Invalid file size.", filepath);
             }
         }
-
+        private double ConvertToRadians(double angle)
+        {
+            return Math.PI / 180 * angle;
+        }
         #endregion
 
         #region Properties
@@ -116,31 +131,55 @@ public SRTMDataCell(string filepath)
         /// <value>
         /// The hgt data.
         /// </value>
-        private byte[] HgtData { get; set; }
+        public byte[] HgtData { get; }
 
         /// <summary>
         /// Gets or sets the points per cell.
         /// </summary>
         /// <value>
         /// The points per cell.
         /// </value>
-        private int PointsPerCell { get; set; }
+        public int PointsPerCell { get; }
+
+        /// <summary>
+        /// Gets or sets the vertical points per cell.
+        /// </summary>
+        /// <value>
+        /// The vertical points per cell.
+        /// </value>
+        public int VerticalPointsPerCell { get; }
+
+        /// <summary>
+        /// Gets the point height in meters.
+        /// </summary>
+        /// <value>
+        /// The point height in meters.
+        /// </value>
+        public double PointHeightInMeters { get; }
+
+        /// <summary>
+        /// Gets the point width in meters.
+        /// </summary>
+        /// <value>
+        /// The point width in meters.
+        /// </value>
+        public double PointWidthInMeters { get; }
 
         /// <summary>
         /// Gets or sets the latitude of the srtm data file.
         /// </summary>
         /// <value>
         /// The latitude.
         /// </value>
-        public int Latitude { get; private set; }
+        public int Latitude { get; }
 
         /// <summary>
         /// Gets or sets the longitude of the srtm data file.
         /// </summary>
         /// <value>
         /// The longitude.
         /// </value>
-        public int Longitude { get; private set; }
+        public int Longitude { get; }
 
         #endregion
 
@@ -158,12 +197,38 @@ public SRTMDataCell(string filepath)
         /// Represents errors that occur during application execution.
         /// </exception>
         public int? GetElevation(double latitude, double longitude)
+        {
+            var bytesPos = GetBytePositionByCoordinate(latitude, longitude);
+            return ReadByteData(bytesPos);
+        }
+
+        /// <summary>
+        /// Method responsible for obtaining a byte position by coordinate.
+        /// </summary>
+        /// <param name="localLat">Local latitude within the data cell</param>
+        /// <param name="localLon">Local longitude within the data cell</param>
+        /// <returns>Byte position</returns>
+        public int GetBytePositionByCoordinate(double latitude, double longitude)
         {
             int localLat = (int)((latitude - Latitude) * PointsPerCell);
-            int localLon = (int)(((longitude - Longitude)) * PointsPerCell);
-            return ReadByteData(localLat, localLon);
+            int localLon = (int)((longitude - Longitude) * PointsPerCell);
+            return ((PointsPerCell - localLat - 1) * PointsPerCell * 2) + localLon * 2;
         }
-        
+
+        /// <summary>
+        /// Method responsible for obtaining an elevation by byte position.
+        /// </summary>
+        /// <param name="bytesPos">The byte position</param>
+        /// <returns>The elevation</returns>
+        public int? GetElevation(int bytesPos)
+        {
+            if ((HgtData[bytesPos] == 0x80) && (HgtData[bytesPos + 1] == 0x00))
+                return null;
+
+            // Motorola "big-endian" order with the most significant byte first
+            return (HgtData[bytesPos]) << 8 | HgtData[bytesPos + 1];
+        }
+
         /// <summary>
         /// Gets the elevation. Data is smoothed using bilinear interpolation.
         /// </summary>
@@ -204,7 +269,7 @@ public SRTMDataCell(string filepath)
         }
 
         #endregion
-        
+
         #region Private Methods
 
         /// <summary>
@@ -217,18 +282,23 @@ public SRTMDataCell(string filepath)
         private int? ReadByteData(int localLat, int localLon)
         {
             int bytesPos = ((PointsPerCell - localLat - 1) * PointsPerCell * 2) + localLon * 2;
+            return ReadByteData(bytesPos);
+        }
 
+        /// <summary>
+        /// Method responsible for reading byte data from data cell file.
+        /// </summary>
+        /// <param name="bytesPos">The byte position</param>
+        /// <returns>Height read from data cell file</returns>
+        private int? ReadByteData(int bytesPos)
+        {
             if (bytesPos < 0 || bytesPos > PointsPerCell * PointsPerCell * 2)
                 throw new ArgumentOutOfRangeException("Coordinates out of range.", "coordinates");
 
             if (bytesPos >= HgtData.Length)
                 return null;
 
-            if ((HgtData[bytesPos] == 0x80) && (HgtData[bytesPos + 1] == 0x00))
-                return null;
-
-            // Motorola "big-endian" order with the most significant byte first
-            return (HgtData[bytesPos]) << 8 | HgtData[bytesPos + 1];
+            return GetElevation(bytesPos);
         }
 
         private double Lerp(double start, double end, double delta)