Skip to content

Latest commit

 

History

History
261 lines (138 loc) · 21.8 KB

TROUBLESHOOTING.md

File metadata and controls

261 lines (138 loc) · 21.8 KB

Troubleshooting Manual

OpenAthena™ for Android

Troubleshooting Manual for the Android version of the OpenAthena project

OpenAthena™ allows common drones to spot precise geodetic locations.

🖼️👨‍💻 + 🧮⛰️ = 🎯📍

OpenAthena Drone Camera Terrain Raycast Concept Diagram

OpenAthena Android splash screen demo

OpenAthena™ Android Target Calculation demo using cobb.tif and DJI_0419.JPG, output mode WGS84

OpenAthena Android DJI_0419.JPG target shown in Google Maps satellite view

OpenAthena for Android triggers a waypoint to show in Android Team Awarness Kit at the calculated location

Preface

OpenAthena™ for Android is designed to be usable by operators without the need for explicit technical training. A downside of this however is that fail conditions of the software can occur without the user having technical insight into why.

OpenAthena is designed to fail safe. If data is known to be inaccurate, unusable, or incomplete enough for a calculation, the software will abort the calculation rather than provide an inaccurate result.

This troubleshooting manual provides important context on common fail conditions and why they occur. This context is important for operators so they may overcome fail conditions which occur in certain specific conditions and adapt their use of the software to overcome them.

Common failure conditions

ERROR: failed to load DEM, not a GeoTIFF ".tif" or DTED2 ".dt2" file

OpenAthena Android an example of DEM load failure error

OpenAthena requires a Digital Elevation Model (DEM) representing terrain altitude of an area of the earth to be loaded before calculations may be performed.

This error may occur when the user or the app attempts to load a DEM from the application directory.

(Despite the content of this message, OpenAthena does actually supports DTED3 (.dt3) files as well)

The DEM loading process is automated in some versions of the software (v0.21.0 and higher) when internet connection is available. Otherwise, download and load an elevation model within the app (v0.21.0 and higher) while you have an internet connection. Alternatively, follow the instructions in the document "EIO_fetch_geotiff_example.md" for obtaining an elevation model using OpenTopography.org:

https://github.com/Theta-Limited/OpenAthena/blob/main/EIO_fetch_geotiff_example.md

The software may only operate offline if a DEM covering the Area of Operations (AO) has been downloaded beforehand.

The failed to load DEM error can also occur in the following conditions:

  • Your selected file was not a DEM, e.g. you selected a regular image file
  • The selected DEM file was valid but not high enough in resolution (e.g. DTED level 0 or 1 files)
  • Your DEM file is corrupted. Certain software, such as most Apple mail clients and the Signal messaging app, incorrectly treats GeoTIFF as regular TIFF images. When it attempts to automatically compress the file before transit it can corrupt its contents. Prevent corruption by zipping the file before sending it and unzipping the file on the recipient's device before loading it into the app.
  • Your DEM file is in a format not compatible with this software. OpenAthena for Anrdroid does not support .zip archives, including those containing multiple elevation model tiles (as is commonly used with ATAK)

How to obtain a Digital Elevation Model for your AO:

To use this app, you need a GeoTIFF or DTED (resolution level 2 or higher) Digital Elevation Model (DEM) file covering your Area of Operations. DEM files store terrain elevation data for an area on Earth. OpenAthena performs a simulated ray-cast from a drone camera's position and orientation towards the digital twin of Earth terrain represented by the elevation model. This technique is used by the software to precisely locate any pixel within a given drone image.

GeoTIFF DEM files obtained from the STRM GL1 30m tend to produce more accurate target results than DTED files.

OpenAthena for Android v0.21.0 and higher can automatically download DEM files when an internet connection is present. It also allows the user to download a custom-specified area (Manage Elevation Models -> Load New DEM) for later use offline. Downloaded DEMs are saved in the application cache directory where they may be automatically loaded by the app whenever you load a drone image from the corresponding area.

To obtain a GeoTIFF file for a certain area outside of the OpenAthena app, review the document "EIO_fetch_geotiff_example.md" https://github.com/mkrupczak3/OpenAthena/blob/main/EIO_fetch_geotiff_example.md

ERROR: resolveTarget ran OOB at: 00.000000, 00.000000, Please ensure your DEM file covers the drone's location!

OpenAthena Android an example of a raycast calculation out of bounds error

This error indicates that the attempted raycast for your target calculation went Out Of Bounds (OOB) of the coverage of your loaded DEM. This most commonly means that your loaded DEM file does not cover the area the drone photo was taken in. This error can also occur however when the raycast misses terrain entirely, such as when a selected point is of the sky or the pitch angle value of the camera is inaccurate.

ERROR: bad altitude or terrain data. This image is unusable. 🖼🚫🎯

OpenAthena Android an example of an unusable image error

This error indicates that the attempted raycast's start height was already below that of the terrain model. This only occurs in situations where either the drone altitude, the terrain model, or both are inaccurate.

The following are common causes of this error:

  • Older DJI drone models incorrectly report their altitude as the difference from their launch point rather than relative to sea level. There is no mitigation, data from such drone models is unusable
  • Altitude data from the drone is inaccurate. To mitigate occurrence of this error, let the drone sit at its launch position longer to acquire a better GPS lock before takeoff.
  • The elevation model height at the location the picture was taken is higher than actual terrain. This commonly occurs in areas with dense vegetation (especially in the southern hemisphere) or urban areas with tall buildings. In such scenarios, the first radar return from the satellite for the SRTM mapping mission came from the tallest object rather than terrain. To mitigate this error, use an alternative Digital Terrain Model (DTM) rather than Digital Surface Model (DSM). FABDEM is one such existing commercial offering which attempts to remove the effect of forrests and buildings.

ERROR: EXIF metadata not found!

The loaded image did not contain the metadata that is necessary for calculation. Many social media sites and messaging platforms automatically remove EXIF metadata from shared images in an attempt to protect user privacy. To mitigate this error, use an alternative messaging method such as email which does not remove EXIF data.

This error can also occur for drone models which do not store EXIF metadata in the first place. Such drone models are incompatible with OpenAthena.

ERROR: XMP metadata not found!

OpenAthena Android an example of a xmp metadata not found error

Similar scenario as above.

ERROR: Unable to open image file to calculate. Drone image 🖼 metadata is either missing or unusable. Is this a drone image?

OpenAthena Android an example of an invalid image error

This error indicates that usable metadata could not be found within the image. This most commonly occurs when the loaded image is from something like a screenshot rather than an actual drone image file.

ERROR: make EXAMPLE not usable at this time

OpenAthena Android an example of an unreconginzed camera make error

This error indicates that the camera/drone manufacturer which took the image is not yet supported.

OpenAthena does not work with images taken by smartphones. The software's terrain-raycast technique requires an elevated view and accurate metdata indicating position and orientation of the camera. Smartphone images do not provide such preconditions and are thus incompatible with OpenAthena.

If you would like to make OpenAthena compatible with your drone model, please send example images to support@theta.limited via email along with the make and model name of your drone. For enhanced accuracy, inquire via the support email and Theta may ship you a calibration pattern poster to use your drone camera with our camera calibration script at no cost to you.

If you are technically inclined, for faster integration consider forking the repo and submitting a Pull Request on GitHub. For new drone makes, you need to extend the function getMetadataValues in MetadataExtractor.java. Additionally, you will need to create an entry for your drone model in our DroneModels database to achieve accurate results.

⚠️DANGER: Autel drones have known accuracy problems ⚠️

OpenAthena Android an example of an Autel drone inaccuracy warning

Drones made by Autel Robotics typically have numerous firmware and hardware issues (this author's personal observation, not an disparagement). During development of OpenAthena, this author observed cases where metadata tags were misspelled, the reported vertical datum for altitude was incorrect, and other significant issues. Additionally, the drone hardware itself (excepting sensor payloads) is generally of inferior quality to DJI and other contemporaries.

This error message will occur the first time an Autel drone image is loaded into a user's session of operating the app. It is intended to inform the user of possible accuracy problems which may occur, while still allowing them to proceed with calculation if they wish to do so.

ERROR: metadata not found! This drone is incompatible with OpenAthena! 😭

This error can occur in rare cases where a certain necessary parameter, such as camera pitch angle, is not present in the image metadata.

ERROR: Camera Pitch metadata found, but was invalid! This drone is incompatible with OpenAthena! 😭

OpenAthena Android an example of an error with the DJI Mini 2 or 3

This error occurs in rare cases with specific low end consumer-oriented DJI drone models (such as the Mini 2 and Mini 3, not inc. Pro versions). For these models, the manufacturer has intentionally removed camera pitch and yaw metadata, likely for the purpose of market segmentation to prevent these models from being used with professional image post-processing software.

Resolving accuracy issues which occur during operation

Accuracy issues occuring during the app's opperation are typically caused by three factors:

  • Slant angle from drone camera to target is nearly parallel to the ground. Circular Error via terrain-raycast is much higher than normal in such cases
  • Poor magnetometer (compass sensor) calibration of the drone. Unless a calibration procedure is performed for the drone's compass while within 100 miles of the operating AO, heading information from the drone's compass can be off by up to 10 degrees or so, causing significant circular error which increases with distance.
  • Camera intrinsic parameters are not present within the DroneModels database for the loaded drone image. In the target calculation output trace text, if the Is camera model recognized? value is No, this means internal properties of the camera were calculated using a less accurate fallback method. In this case, calculations will become more inaccurate the further the selected pixel is from the central point of the image.

Compass sensor 🧭 calibration

It is strongly suggested that you should calibrate the drone's compass sensor for the local environment before taking photos to be used with OpenAthena. Consult your drone's operation manual for this procedure. The image metadata from an un-calibrated drone can be several degrees off from the correct heading. This can result in dramatic target-resolution inaccuracies if the sensor is not calibrated. Always verify a target match location from OpenAthena before use!

E.g.:

OpenAthena Android an example of a bad target resolution due to an un-calibrated magnetometer compass sensor

Optional: use the "Manual Azimuth Correction" slider to correct bad compass data

If you find your aircraft's compass sensor is still not providing correct heading information, you can use this slider to manually apply a configurable offset anywhere in the range of [-15.0°, +15.0°]. This offset will be added to your aircraft's camera heading before target calculation is performed:

OpenAthena Android Manual Azimuth Correction Slider

NOTE: This value is NOT for setting magnetic declination! Magnetic declination is already accounted for by your drone's onboard digital World Magnetic Model (WMM). Improper use of this Manual Offset setting will result in bad target calculation output.

Your selected manual correction value is saved automatically between launches of the app. To reset the value, tap the "RESET" button in the Settings screen or move the slider to the middle.

Let your drone acquire GPS lock before flying

For the best results for target calculation, it's important to let your drone sit at the launch position until it can get an accurate GPS fix. This is important for it to be able measure altitude correctly during flight.

On DJI drones, this indicator shows the number of GPS satellites visible to the drone:

A screenshot of the UI for DJI Go 4 during flight of a Mavic 2 Zoom drone. The GPS connection indicator is highlighted

Wait until at least 6 GPS satellites are visible (or you can confirm the GPS fix is good) before starting flight.

Application Settings ⚙:

OpenAthena for Android supports multiple output modes for target calculation, including:

To change the ouptut mode of OpenAthena for Android, tap the kebab menu icon (three dots) at the top-right corner of the screen and select "Settings":

OpenAthena™ Android 🎯 Output Modes Activity demo WGS84

Select your desired output mode by pressing its button in the list:

OpenAthena™ Android 🎯 Output Modes Activity demo NATO MGRS 10m

Then press the back button or again tap the kebab menu icon (three dots) to return to the "Calculate" screen:

OpenAthena™ Android Target Calculation demo using cobb.tif and DJI_0419.JPG, output mode NATO MGRS 10m

The app also supports selection between Meter and US Foot as the Distance Unit for the app's output.

ATAK Cursor on Target

When the "✉️" button is pressed, OpenAthena will send a Cursor on Target (CoT) multicast UDP packet to udp://239.2.3.1:6969 to all devices on the same network as your device. Under default settings, this will cause a marker to show up in ATAK at the target location for all recipients:

OpenAthena for Android triggers a waypoint to show in Android Team Awarness Kit at the calculated location

If your Android device running OpenAthena is not connected to any network at all, the ability to send CoT from OpenAthena to your locally-running ATAK app will be degraded. This is a known bug with the current version of the app.

OPENTOPOGRAPHY_API_KEY in local.properties for DEM downloading

The OpenAthena app's automatic DEM downloading feature requires an Application Programming Interface (API) key from OpenTopography.org (obtainable here) to function. Such an API key authenticates the app with OpenTopography's servers for DEM downloading. A default key will be automatically included in releases from the Google Play or Apple AppStore; however, you will need to obtain one for yourself if you clone this project's code from GitHub or download it from F-Droid.

If you have cloned and built this project but did not provide an OpenTopography API key, OpenAthena will be unable to download DEM data.

Add your OpenTopography API key from within the OpenAthena app

If you have downloaded OpenAthena™ from GitHub or F-Droid, you will be prompted the following upon your first time opening the app:

Greetings! Thanks for installing OpenAthena™ for Android. Online features of this app (for downloading terrain elevation data) require you to obtain an OpenTopography.org API Key (passcode) and set it within this app Accept/Reject

Select the option "take me there now!" to go to the screen for obtaining and inputting your API key (it can also be accessed at any time from the 3 dot action menu on the top right).

You will see "API Key Status: X (Invalid)", with a description and link below:

OpenAthena for Android Manage API Key activity. The app shows the current API key is missing or invalid

Click on the link to be taken to the OpenTopography.org website. There, create an account, sign in, go to the "MyOpenTopo Dashboard", and click on "Get An API Key":

OpenAthena™ Android Open Settings Activity demo

Finally, paste your API key into the OpenAthena™ for Android app and hit the "Apply button":

OpenAthena™ Android Open Settings Activity demo

If you have an internet connection, the API Key Status should appear as ✅ (Valid). If you are offline the status will appear as ❓ (Unknown). If your API key is in fact valid, the software will work correctly with the OpenTopography API for DEM downloading once internet connection is restored.

How to Acquire and use an OpenTopography API Key for building this project

Follow the instructions in the link below to obtain an API Key for OpenTopography.org:

https://opentopography.org/blog/introducing-api-keys-access-opentopography-global-datasets

After cloning this project, edit the file local.properties which is auto-generated by Android Studio in the root directory of the project. It should have appearance similar to below:

## This file must *NOT* be checked into Version Control Systems,
# as it contains information specific to your local configuration.
#
# Location of the SDK. This is only used by Gradle.
# For customization when using a Version Control System, please read the
# header note.
#Tue Jun 14 14:32:24 EDT 2022
sdk.dir=/home/YOURNAME/Android/Sdk/

Add a new line to the end of the local.properties file:

OPENTOPOGRAPHY_API_KEY=nlhhp3yd9ud54tr3eem4akqv49wcb23i

...replacing nlhh...23i with the OpenTopography API key you obtained from the above link

You will then be able to build the project and the API key will be included in the app.