Theodolite User Manual
Theodolite / Theodolite HD
User Manual

Updated July 25, 2023 - Version 9.0.1

Copyright © 2009-2023
Hunter Research and Technology LLC
Quick Links
Main Screen Functions
This section discusses some of the buttons on Theodolite's main screen.
PREFS (Preferences)
Tap the "PREFS" button in the upper left corner of the screen to see settings for the compass (true or magnetic), units (ft or m), camera mode and options, angle display (degrees or percent grade), angle mode, geodetic datums, position format, augmented reality (AR) layers, and advanced options (compass sensor algorithm). Available position formats include decimal and D-M-S latitude/longitude (absolute and relative), MGRS, UTM, Banded UTM, British National Grid, Irish National Grid, US National Grid, Maidenhead locator system, Map Grid Australia, and optional US State Plane Coordinates. To see a full list of position formats and examples, look here. The preferences section of the app also provides a link to this help page.
MAP
This button opens Theodolite's built-in map, giving access to features like location search, map marker sharing, and team tracking. More information about Theodolite's maps and map functions are discussed in sections below.
◀N▶
This button enables compass correction mode, taking you to a screen where you can slide a finger sideways to adjust the compass offset. You can use AR layer objects like the sun, moon, Polaris (North star), or mountain summits as references, or any landmark as a reference. More information on compass correction mode is given below.
ZERO
Tapping this button will zero all angles at a given orientation of the device, thereby showing angles relative to that reference until you tap the button again. Zero mode cannot be activated when the A-B calculator is in use.
A-B
Tapping this button brings up Theodolite's A-B calculator, used for computing distances and heights, headings, and triangulations.
CAL
Tapping this button will bring up a calibration screen, where you can aim/position your device camera to align with a known level horizon/elevation reference. The calibration procedure will then measure offsets in the acclerometer, gyro, and camera hardware and use them to correct measurements to match the level reference. Note: only attempt calibration if you have a proper fixture to align and position your device and a level elevation/horizon reference accurate to less than 0.1 degrees.
NIGHT (Theodolite 8) or COLOR (Theodolite 9)
This button cycles between different display colors, brightness levels, and filter, which customize the app's look and may be helpful to preserve night vision or improve usability in different lighting situations. The same button toggles the display back to normal after all the options have been cycled through.
ZOOM
This button toggles the zoom level of Theodolite's main display between 1X, 2X, and 4X. On devices with an additional ultra wide lens (some dual lens devices and all triple lens devices) there will be an extra 0.5X zoom mode. On devices with an additional telephoto lens (some dual lens devices and all triple lens devices) an additional 8X zoom mode will be available.
CAMERA
This button is used to take photos and screenshots or record movies. The app's camera mode can be changed via the PREFS button > Camera Options.
LOG
Tapping this button brings up the data logging popup, with buttons to add a data record (data only), add a data record with a note, copy the data log to the system-wide clipboard (where it can be pasted into other applications), export the data log, and clear the data log (deleting all points). The data log is formatted as plain text with a header and a space-delimited line for each data record. Each log record includes the following data: date, time, latitude, longitude, formatted position, altitude, datum code, heading (deg), heading (mils), elevation angle, and horizon angle (for a list of datum codes and descriptions, see here). Export of the log includes a KML file and CSV file with all data records.
MAIL
Tapping this button generates an e-mail containing current data, URLs to open the current location in Theodolite, Gaia GPS, Google Maps, and Apple Maps, a screenshot, and a KML file (usable in Google Earth, AutoCAD, and many other applications). For this button to be active and function properly, you must have a working mail account (capable of sending mail) setup in the default iOS Mail app.
Reticles
Tap the center of the screen to cycle between the 11 available reticles and rangefinders in Theodolite.
Taking Photos and Screenshots
Theodolite has two modes for taking still images. The regular photo mode takes a still image at the camera's maximum resolution, and offers options (in camera settings) to overlay the image with a center crosshairs, a data stamp showing date, time, geo-data, and zoom level, and a custom user-entered note. The overlay font is scaled to the image size, and has settings for white, yellow, or green colors (all rendered with a transparent black drop shadow for legibility on any background). If available on the device, the flash can be used in manual or automatic mode.

Theodolite's screenshot mode captures exactly what is seen on the screen, and is rendered at the device's screen resolution. In screenshot mode, flash is not used.

In both modes, image saves are buffered and done in a background thread, so that you can continue to shoot photos while image saves are in progress. With multitasking, image saves will continue after you leave the app.

Images are saved to the device photo album, and are written with an EXIF metadata record containing position, altitude, bearing, and user notes. Theodolite 5 and later adds data for elevation and horizon angles to the EXIF record, as plain text in the TIFF "image description" field and as XML data in the EXIF "maker note" field.
Movie Recording
Theodolite 3.0 introduced an exciting new feature frequently requested by users -- the ability to record movies in the app. The regular movie mode is similar to the photo mode in Theodolite, recording a basic video with options to show an overlay with crosshairs, geo-data, and a custom note. The screen movie mode is similar to the screenshot mode, capturing the entire screen display including the full graphics overlay. Both movie modes offer multiple video quality settings, and both record audio along with video. On capable devices, the torch can be used for lighting the video scene in regular movie mode.

On devices capable of HD recording, there are three video quality settings. Low records 4:3 at 480x360, medium records 4:3 at 640x480, and HD records 16:9 at 720p or 1080p (whichever the device supports).

On devices that do not support HD recording, only two video quality settings are available. Low records 4:3 at 480x360 and high records 4:3 at 640x480.

Note that onscreen rangefinders will only be displayed in 4:3 video modes.

Movie capture occurs in two stages; first, the movie is recorded, and then it is processed to add information such as watermark overlays and screen graphics overlays. For the best performance, processing is run in the foreground as a modal task. If recording or processing are interrupted (such as by a phone call or other multitasking event in iOS) Theodolite will give you the option to process an interrupted recording, resume processing the movie, or delete the movie once you return to the app.

After a movie has been processed, it is saved in a background thread and you can continue using Theodolite, or leave the app, while the save is in progress. Movies are saved to the device photo album as ".mov" files, using H.264 video encoding and AAC audio recording (with audio bit rates ranging from 700 kbps to 10.5 mbps).

Note: Recording and processing movies in Theodolite is extremely computationally intensive, so this feature must be used carefully and wisely. It is not intended for extended movie recording or continuous monitoring, but rather, for short recordings (in the range of 10-20 seconds) in scenarios where Theodolite is typically used to make measurements or document observations and findings.

For the fastest performance, use the regular movie mode with lower video quality settings. In this mode, processing will take 1-4 seconds for every 1 second of recorded video on a typical device. This processing overhead can stretch to as much as 10-15 seconds of processing per 1 second of recording when using screen movie mode in HD quality on devices with retina screens!

It's advisable to experiment with your device in typical usage scenarios, to find the right balance between quality and processing time.

Medium video quality is sufficient for most purposes, and works well in screen movie mode. In fact, since screen movies are sized to the dimensions of the device screen, using HD quality doesn't really offer much benefit for screen movies unless your device screen resolution is HD or better.

HD quality is mainly intended for recording regular movies in cases where wide screen format or crisp watermarks are desired, and/or in cases where the user is willing to accept the additional processing overhead to get maximum video quality.

You may also want to experiment with the systemwide screen recording mode in iOS 11 and later, which may be suitable for your use and have a lower overhead, albeit with more limited options.
Optical Rangefinders
Theodolite's rangefinders allow you to quickly estimate distance to targets, objects, and landmarks, provided you know some dimension of the object in view. These rangefinders have been implemented through significant development and testing.

To cycle through the various rangefinder reticles in Theodolite, tap the center of the screen. Note: rangefinder reticles are only available when the camera format is 4:3, which occurs in Theodolite's photo/screenshot mode and lower resolution movie modes. When the camera format is widescreen (using the HD quality setting on capable devices) rangefinder reticles will be turned off.

The first rangefinder is a distance/size multiplier-type rangefinder using rings. Default rings are 2x, 4x, 8x, and 16x, which indicate scale factors between distance to the object and the object size (ring diameter). Note that the scale factor and availability of the rings will change with Theodolite's zoom level and the device's camera lens configurations.

As an example of usage, consider the storage shed shown in the screenshot clip below. The corner of the shed, known to be about 6 feet high, lines up with the "16" ring on the rangefinder. This indicates that the distance to the shed is approximately 16 times that height dimension; ie, 16 x 6 = 96 feet. The distance was later measured with a tape to be 98 feet, meaning Theodolite's optical estimate was within 2% -- pretty good.


For best results, the object should be framed in a straight level view, but off-angle variations of up to 10-15 degrees won't affect accuracy too badly. Any dimension of the object can be aligned with the reticle rings, whether vertical, horizontal, or diagonal.

The rangefinder reticle rings have been setup to work on all current devices, taking into account the lens field of view and the screen resolution. However, the rangefinder can be calibrated -- both to accomodate future devices and to improve results when user-specific applications dictate a particular range of measurement. To calibrate, simply drag the "CAL" handle in a circular motion to "focus" the rings on a landmark with a known distance:dimension ratio matching one of the rings. You can double-tap the handle to reset the rings to the default calibration.

The next rangefinder is also ring-based, but uses NATO mil markings on the rings, for users familiar with military types of range measurements (used by snipers and artillerymen). It functions just like the scale factor rings, but instead uses scales of 100-600 mils (where 6400 mils = 360 degrees).

Next up is a standard mil-dot crosshair reticle. Dot spacings are 20 mils at 1X zoom, 10 mils at 2X zoom, and 5 mils at 4X zoom.

Next, Theodolite includes two large format stadiametric rangefinders, similar to those used by snipers, hunters, and artillerymen. The first stadiametric option shows distance/height multipliers, and is usable with any reference target. By lining up the target with the curve scale, distance to the target can be estimated as a multiple of the target height. Note that the horizontal scale of the stadiametric curve is linear, such that graphical interpolation is possible.

The second stadiametric rangefinder is unit-based, showing yards to a 5'7" stadia (when length units are set to ft) or meters to a 1.7m stadia (when length units are set to m). It also uses a linear horizontal scale to allow interpolation.

Finally, Theodolite 3.1 introduced a variable 4X-24X rangefinder scope reticle. Drag the sizing handle to the right of the square reticle to fit the reticle to a vertical or horizontal dimension of the target. On the left, the scope displays the distance/size multiplier between distance to the target and the target size.
Compass Correction Mode
The ◀N▶ button enables compass correction mode, taking you to a screen where you can slide a finger sideways to adjust the compass offset. You can use AR layer objects like the sun, moon, planets, Polaris (North star), or mountain summits as references, or any landmark as a reference. When using a compass offset, you will see a small ◀▶ symbol on the left of the compass readout.

Compass correction is meant to be for temporary use, as errors and offsets in the device compass are not generally repeatable or consistent, or the same from location to location. The correction you dial-in for one location and viewpoint is unlikely to be relevant when changing to another location and viewpoint. So please be sure to use this compass correction mode with realistic expectations, and reset/readjust the compass correction offset whenever location and/or viewpoint changes.

When using the correction mode with compass+gyro, the device magnetometer is still used to set an absolute reference for the compass and azimuth measurements. That absolute reference is simply adjusted by the offset you have dialed in. Accuracy is the same as the base compass accuracy.

When using gyro-only, the device magnetometer is no longer used. This mode can measure azimuthal angle variations with high accuracy (1 degree or better) but is subject to drift over time, and susceptible to error from large magnitude rotations (which can overwhelm the gyro sensor). When using gyro-only mode, drift will be minimized and repeatability enhanced if you make gentle rotations of the device. This mode can be extremely useful for shooting accurate bearings and making surveys, but it's important to occasionally return back to shoot the bearing of a known reference to make sure drift has not become an issue.

Because gyro-only mode depends on time integrations of rotation rate data from the gyro sensor, it can only function while Theodolite is the active app. Gyro-only mode will be cancelled, and the compass correction reset to zero, whenever Theodolite is put in the background.
A-B Calculator
These functions calculate information from two observation readings, A and B. Theodolite will remember data from both points if you leave the app before completing a calculation. For long distance measurements, you can record data at point A, leave the app, travel to point B, and reactivate the app to record data and proceed with a calculation. A and B measurement points can be shared with other users of Theodolite via SMS text message or e-mail from the app's built-in map, to allow for distributed and team measurements. Note: A-B functions cannot be used when Zero Ref mode is active.
A-B Distance/Heading
Tap the A button at location A, then travel to location B and tap the B button. Theodolite will calculate the distance and heading between the two points (using their latitude/longitude coordinates). Be mindful of the Cell/GPS position accuracy (shown by tapping the green/red status icons on the main screen) when using this option, as it affects the accuracy of the result. The greater the distance between points A and B relative to the position accuracy, the better the results will be. Upon completion, points A and B will be shown on the map along with the bearing line between the two points.
Height from A-B Elevation Angles
Aim at the bottom of the object to be measured and tap the A button, then aim at the top of the object and tap B. Theodolite will ask you to input the horizontal distance to the object, then it will calculate the object's approximate height based on the change in elevation angle between A and B. This is useful when you can easily make or estimate horizontal measurements but not vertical ones. You do not need to be on level ground for this measurement. Note that you do not need to specify units for this measurement -- the computed height will have the same units as the input distance.
Distance from A-B Elevation Angles
Similar to above, but solves for horizontal distance assuming the object's height is known. Aim at the bottom of the object to be measured and tap the A button, then aim at the top of the object and tap B. Theodolite will ask you to input the height of the object, then it will calculate the approximate distance to the object based on the change in elevation angle between A and B. This is useful to calculate range/distance to objects and landmarks with known height. You do not need to be on level ground for this measurement. Note that you do not need to specify units for this measurement -- the computed distance will have the same units as the input height.
Alternately, you can use your height to estimate distance to an object as shown below -- aim at the bottom of a far off object for point A, then aim level (zero elevation angle) for point B. Then input your eye height, or more specifically, the height of your device. Theodolite will calculate the approximate distance to the object. This measurement does require that the user and object are on level ground.
Distance and Height from A-B Elevation Angles
This method calculates distance and height simulataneously, though accuracy is reduced from the methods discussed above. In this case, the device height is used as the reference input along with the A and B elevation angles. This measurement requires that the user and object are on level ground. Note that you do not need to specify units for this measurement -- the computed distance and height will have the same units as the input device height.
A-B Delta Angles
Theodolite will calculate the difference in elevation, horizon, and azimuth (if available) angles between points A and B. Useful when you need to know the relative angles between two objects from a common position.
Point C from A-B Triangulation (compass-equipped devices only)
From location A, aim at an object or landmark in the distance and tap the A button. Then travel to location B, aim at the same object, and tap the B button. Theodolite uses the latitude/longitude position and azimuth recorded at points A and B to triangulate point C, the approximate location of the object/landmark you were aiming at. It also provides distances between the three points. Upon completion, points A, B, and C will be shown on the map along with bearing lines between the three points.

Be mindful of the Cell/GPS position accuracy and compass accuracy (shown by tapping the green/red status icons on the main screen) when using this option, as they greatly affect the accuracy of the triangulated result. The greater the distance between points A and B relative to the position accuracy, the better results will be.
Note that there are several cases in which triangulation cannot occur: if points A and B are the same, if bearings from A and B do not intersect, or if the bearings from A and B do not form a triangle. For the best results, the angle between azimuth A and B (ie, the angle at point C) should be at least twice as big as the compass accuracy and no larger than about 160 degrees.
Show A-B Points on Map
After recording points A and B, they will both be shown on the Map.
Hardware/Sensor Status and Accuracy
Theodolite shows hardware status and accuracy with a series of green or red dots located in various areas of the main screen. Along the top of the screen, dots indicate status of position, altitude, and datum. The position and altitude dots will flicker when the device GPS hardware is actively seeking a position and altitude fix, and will remain solid when locked on. Dots on each side of the screen report status of gyro/accelerometer hardware used to measure horizon and elevation angles, and the dot on the bottom of the screen reports status of gyro/magnetometer hardware used to measure compass angle.

To see detailed accuracy information, tap any of the green/red status indicators on the screen. Information on the accuracy screen is updated in realtime.

The accuracy of position, altitude, elevation/horizon, and azimuth measurements in Theodolite are determined by the hardware and sensor capabilities of your device, the location of measurement, and the quality of GPS signals and sensor readings.

Under optimal conditions (clear line of sight to the sky with signals from at least four satellites), the newest iOS devices generally have a position accuracy of 10-15 feet and an altitude accuracy of 10-20 feet.

With no magnetic interference, the latest iOS devices can generally measure azimuth with an accuracy of 5-10 degrees.

Devices with a gyro and accelerometer can measure elevation/horizon angles to 0.09 degrees accuracy, while devices with only an accelerometer are accurate to 0.9 degrees.

All accuracy numbers reported in Theodolite are based on hardware specs and realtime accuracy information provided by Apple through iOS. The application itself does not determine or influence accuracy; however, the displays in Theodolite are setup to show levels of fidelity, resolution, and proper number of significant digits that are appropriate for the available hardware accuracy.

Note: Theodolite 6.0 added an additional digit of decimal precision to latitude and longitude display (out to 6 decimal places), but this does not imply that internal GPS hardware can provide this level of accuracy. If you require location data to the 6th decimal place, be sure to use a sub-meter BlueTooth GPS accessory that can deliver this level of accuracy.
Live Map Markers
Theodolite 3.1 introduced live map markers that continually update to show distance and heading to the marker from the current location. This information is displayed on the left side of the marker's popup annotation.


Theodolite 5 introduced a live distance/bearing display on Theodolite's main camera view, which shows distance and bearing, as well as aim indicators, pointing to the active map marker selected on the map view. This is shown in the lower left corner of the main screen. In Theodolite 9, this was improved to show a floating marker flag in the viewfinder display when it would be in the field of view. At long range (farther than 30 meters) the marker is rendered in a vertical ribbon on the screen. At close range (within 30 meters) the marker is rendered to appear on the ground based on the current altitude of the device, with the assumption the device is held 1.5 meters above ground (average chest-eye height). If local terrain is highly variable or the device is held much lower or much higher than 1.5 meters above ground, this rendering will not be fully accurate until you get closer to the actual marker location on the ground.
Tap the magnifying glass button on the map screen to search for a location and center it in the map view. Use the selection buttons to specify the format for the search input -- address (such as city,state or street address, or even locations like "Yosemite National Park"), decimal latitude and longitude (separated by comma), MGRS, UTM, UTM-B (MGA), or USNG. For readability, you can use spaces between text blocks when entering MGRS, UTM, UTM-B (MGA), or USNG coordinates, but they are not required. Theodolite will check all input coordinates and alert you to any errors in format.
Sharing Map Markers
Theodolite 2.7 introduced the ability to share map markers with other users of the app via SMS text messaging and e-mail. To access this feature, tap any marker shown on the built-in map, and then tap the action button on the marker's popup and select one of the share options. Data shared from normal markers includes position and marker name. Data shared from A or B points (created with Theodolite's A-B calculator) include position, altitude, azimuth, elevation angle, and horizon angle. This allows users to share A-B measurement points for distributed and team calculations. For example, users could aim at a common landmark from two different positions (one designated A, the other designated B), and then share that data to compute the position (point C) of the landmark. Or users at different positions could share data to compute the distance and heading between their positions.

When sharing a map marker via SMS text message, a special data URL is transmitted to the recipient. When sharing via e-mail, a formatted message is sent containing a link with an embedded data URL. These special URLs will be active and recognized on any iOS device with version 2.7 or later of Theodolite or Theodolite HD. When the recipient taps the URL or link, Theodolite will open and import the marker.

Map markers will be imported directly, with the option to edit the marker name (by default, the original marker name is appended with the name of the sender's device). A-B markers will open with an option to import the point as A or B, or as a simple map marker (which only uses position). When importing as A or B, the new point will overwrite any existing A or B points on the receiving device.

Theodolite 3.1 added a sharing URL for the Gaia GPS app, which will allow users of that app to import Theodolite map markers (and vice versa). This feature is only available when sharing map markers via e-mail.
Import/Export of Map Markers
Theodolite 6.0 added options to import and export map markers via iCloud Drive or local device storage, which may be useful for sharing a large number of map markers between users or devices, or transferring waypoints from other apps or programs into Theodolite. Standard KML format is used for map marker files, but users who wish to import a KML file that was not written by Theodolite are first advised to export a KML file from Theodolite, study the contents, and make sure the desired import KML file conforms to the same internal format. When importing map markers, the markers will be added to any existing markers already stored on Theodolite's map. A sample Theodolite map marker KML file is available here.
Theodolite Sharing URLs
Theodolite data sharing can be implemented in websites, e-mails, texts, and other apps. Simply use one of the URL formats shown below:

     theodolite://marker?name=My%20Marker&lat=39.266094&lon=-78.757088

     theodolite://abpoint?name=Point%20A&lat=39.266094&lon=-78.757088&vert=77.949181&horz=-34.549763&az=229.016068

The first scheme is for map markers and passes marker name, latitude, and longitude. The second is for A-B calculator points and passes name, latitude, longitude, vertical angle, horizontal angle, and azimuth angle (true). All numerical data must be in decimal degrees. The WGS-84 datum is assumed for position coordinates. Marker names must be percent-escaped.

For additional questions about Theodolite URL sharing, please contact the developer.
Map Polygon
The option to draw a polygon on the map was introduced in Theodolite 6.1. A polygon can be used to show boundaries of a property, mark a trail, show a route, or draw any other feature that can be represented by connected line segments. If you tap on the polygon button on the map screen, you'll see options to create a polygon or import a polygon, export the polygon as KML via e-mail or iCloud, and delete the polygon.

To manually create a polygon, points can be added at the map crosshair or at the current highlighted map marker. This can be repeated as many times as needed to create a polygon shape. The "close polygon" button will snap a new line from the current end point back to the very first point (you could keep adding points beyond that, but any time you close the polygon it will snap a new line back to the very first point).

Instead of manually creating a polygon, one can be imported in KML format via iCloud Drive. The basic format for a Theodolite polygon KML file is shown in this sample file:

Sample Polygon KML File

Note that importing polygon data adds new points and segments to the existing polygon data already in Theodolite. If you want the imported polygon to start a new polygon shape, you should delete the existing polygon prior to importing data.

The polygon export options will create a file in this same format, using the current polygon defined on the map, and allow you to export via iCloud Drive or e-mail.
Offline Outdoors Maps
Theodolite 5.0 introduced offline Outdoors maps. These exclusive new maps are ready for your outdoor lifestyle whether you're a hiker, sportsman, skier, cyclist, or any other type of outdoor adventurer. They are also ideal for military personnel, surveyors, first responders, search and rescue teams, and other professionals who work outdoors.

Theodolite outdoors maps use detailed coloring and shading to show terrain and land cover with spectacular fidelity, and include topo contours (feet or meters), roads, trails, landmarks, campgrounds, ski lifts, and more. Built on MapBox and OpenStreetMap cartography with worldwide coverage, Theodolite outdoors maps have solid data whether you're in the city or out in the middle of nowhere. And when you really are out in the middle of nowhere, count on Theodolite's new offline map mode to access outdoors maps stored on your device.

Theodolite outdoors maps are paid "per-tile" so you're only paying for what you use, with no subscriptions or time limits. Purchase credits for 1,000, 5,000, 10,000, or 20,000 map tiles, and add more when needed. Both online and offline maps are paid per-tile, but downloaded offline maps are yours to keep, with no additional costs down the road. Map tile credit pricing starts at $0.99 USD (or equivalent) for 1,000 tiles.

Note: Outdoors map tile credits are a consumable in-app purchase, which means the App Store installs them on a per-device basis and does not share them between devices in your App Store account. You must add map tile credits to each device separately, if desired. In addition, the App Store does not provide a restore capability for consumable in-app purchases, which means they could be lost if you do not backup your device and make use of iCloud. Theodolite will save information about your map tile purchases on the device and in iCloud, to allow you to restore purchased credits from backup or transfer to a new device. You are strongly urged to backup your device and to allow Theodolite to use iCloud (see iOS System Settings) in order to restore map tile credits or transfer them to new devices.


To get started with Theodolite Outdoors maps, use the mode selection button (looks like an unfolded map) on the map screen's toolbar to select "Outdoors" mode. For an initial purchase, you will be taken to a description screen with buttons to view pricing and purchase through the App Store. For subsequent purchases, you can tap the map tile counter which appears in the upper left of the map screen when in Outdoors map mode.

Once map tile credits are purchased, you will see a small counter in the upper left corner of Theodolite's map screen when in Outdoors map mode. This counter keeps track of map tile credits remaining, and you will notice that number decrease when browsing a new area or when downloading map tiles for offline use (see below). You can tap the counter to buy more map tiles at any time (it will turn red when fewer than 500 tiles remain).

Theodolite makes use of agressive caching, both in memory and on disk, to minimize repeat downloads of tiles and make the most of your map tile credit purchases. If a previously downloaded tile is in memory or on disk cache, Theodolite will retrieve it instead of downloading the tile from the cloud and using a credit.

To download Outdoors map tiles for offline use, tap the "cloud" button on the map screen's lower toolbar (only visible when in Outdoors map mode). This will bring up a selection box which you can move and resize to capture the region of interest (you can still move and pinch the map to position and zoom it independently of the selection box). The selection box encompasses all tiles shown inside the box at the current zoom level, as well as all tiles needed to support higher zoom levels (to enable zooming in).


When you are ready to download a region, tap the "Download" button in the lower right corner. Theodolite will calculate the number of map tiles required for download (which also indicates the possible number of map tile credits that will be spent if tiles aren't already in cache), and provide an estimate of the amount of disk space required to store those tiles on your device. If you go ahead with download, a progress bar will be shown on the bottom of the screen. Once download is complete, you are asked to name the offline tile set.


Note that downloads of large regions can take a while, so you may want to do those while on a wifi network for the best performance. Please be sure your device has enough free storage space before downloading large offline maps.


To view offline map sets, use the map screen's mode button to change to "Offline" mode. The current active offline set will be shown (or the one you just downloaded, if that's the first set). You'll notice that the cloud button from the Outdoors mode is replaced by a filing cabinet drawer button in Offline mode. That button gives access to all of your offline map sets, allowing you to select a set for viewing or delete a set (tap the "Edit" button to delete map sets).


Also on the map set screen is a switch that toggles whether or not offline maps will be backed up with your device data when backing up to a local Mac/PC or to iCloud (if you have the storage space to backup your offline maps, that option is strongly recommended).


Note: Outdoors maps are tiled, as typical for mobile device maps, and support a large range of zoom levels from continental scale all the way down to house scale. This tiling lets Theodolite efficiently display and render map data no matter how far you zoom in or zoom out. Be conscious of this tiled zoom level approach when setting up offline maps, and focus on reasonably sized finite regions. Theodolite will download tiles for the current zoom level and all higher zoom levels, which means that if you attempt to download a map of a very large region and/or start at a lower zoom level, the map will require a lot of tiles and take up a lot of space on your device. If you focus on reasonably sized regions, or attempt to divide or bracket an area of interest with smaller regions, offline maps will be much more efficient and practical.

We occasionally hear complaints from customers who attempt to download an offline map for a large area, such as an entire US state or an entire country, and become upset upon finding out the map would require more storage than any device could ever accomodate, as well as cost hundreds of dollars in tile in-app purchases. This is just not practical and not what tiled offline maps are for. These types of maps are intended for reasonably sized finite regions, where the convenience of having map tiles at multiple zoom levels stored locally on the device is the main purpose, in situations where cell service and internet access is not available. These types of maps are not intended or practical to cover large areas such as states or entire countries, or create your own private map database of the world. For large arbitrary sized regions, we really need to revert back to online maps where "the cloud" is the database and the device fetches what it needs to see in realtime over the internet. Or use a paper map!

The tile pricing levels available for in-app purchase in Theodolite should accomodate most normal and practical uses of Outdoors and offline maps. In fact, even the starting 1,000 and 5,000 tile packs should cover most users for a while. If you are trying to create offline maps for regions that take an order of magnitude more tiles than the typical tile packs offered for in-app purchase, it means your regions are just too big and/or you're starting at too low of a zoom level. Try being a little more strategic about defining maps and your tile purchases will go a lot farther.
Team Tracking
Theodolite 3.1 introduced team tracking, which automates the sharing and exchange of map position markers for teams with up to 20 members. This feature is available with an additional one-time in-app purchase of $1.99 USD (or equivalent) through the App Store.

Team tracking was developed in conjunction with search and rescue teams to offer a good balance between simplicity and performance. It deliberately avoids using continuous updates and background GPS operations to minimize impacts on battery life. It does not require complicated logins or authentications. All location information is transmitted privately within a team, and members can opt to temporarily disable tracking on their device when additional privacy is needed (for instance, when the team is not on active duty).

Theodolite's team tracking model is simple and has only two modes of operation -- team leader or team member. As a team leader, you can create a team and send invitations out to 19 additional members. As a member, you can accept invitations to join a team. Leaders have the ability to delete/deactivate a team, while members can delete/deactivate their membership. You can only be a leader or member of one team at a time.


To get started with team tracking, tap the "Create" button on the team popup (accessible on the map screen) or accept a team invitation. You will be prompted to complete a one-time in-app purchase through the App Store to activate the team tracking feature. This purchase will allow you to create or join an unlimited number of teams, and the purchase is transferable to all of your devices running Theodolite under your App Store account (note, however, that the in-app purchase is not transferable between Theodolite and Theodolite HD, as they are separate products in the App Store and Apple doesn't allow in-app purchases to transfer between apps). Currently, no additional usage fees are required and the intention is to keep it that way. However, we reserve the right to implement upgrade options or subscription plans in the future.

When creating a team, you must provide a team name and a name for yourself as leader. After the team is created, you can tap the "Invite" button to send invitations to members via SMS text message or e-mail. You can send invitations at any time, up to an overall total of 20 devices (leader + 19 members) on the team.

When joining a team, you will be prompted to provide a name for yourself as a member and then you will be added to the team.

Once the team is active and has members, you will begin seeing green dots on Theodolite's map showing the location of other team members. The team popup always shows the time of the most recent update and the number of active members on the team (active/total stats in square brackets). The team tracking database is updated every 5 minutes whenever Theodolite's map screen is open, and that includes both sending your device's location up to the cloud server and retrieving location of other team members from the cloud server. When periodic tracking updates are required (for example, while a team is on active duty), team members should periodically open Theodolite's map to update their location with the database and download the latest team positions.

In both leader and member modes, an on/off switch on the team popup allows you to turn off tracking and sharing of location information for your device. This is useful in situations when a team is not on active duty and additional privacy is desired. This lets you temporarily disable team tracking on your device without modifying the team setup.

Users are encouraged to provide feedback on team tracking to guide future development. Please let us know how team tracking is working for you, and give suggestions for improvements.
Datums
The optional Datum Pack adds over 230 geodetic datums to the app, covering regions around the world. These datums are used to compute position and altitude from GPS data. The Datum Pack is available with an additional one-time in-app purchase of $2.99 USD (or equivalent) through the App Store.

The default datum used by iOS location services, and Theodolite, is WGS-84 (WGS stands for "world geodetic system" and 84 refers to "1984", the year of this standard). WGS-84 is an ellipsoidal model that approximates the surface of the Earth.

While WGS-84 is a good worldwide compromise for a datum, any datum that attempts to model the entire Earth with a single ellipsoid will have errors in regions where the Earth's actual surface deviates from the ellipsoidal shape. For that reason, local datums are often used in navigation and surveying. These allow a more accurate representation of the Earth surface over smaller regions of interest. Well known datums in North America are NAD-27 and NAD-83, which have subsets covering specific regions like Alaska, Canada, Mexico, and other regions and countries in North America. In Europe, OSGB-36 is well known in the United Kingdom, and ED-50 is commonly used in other European countries.

Theodolite's optional Datum Pack includes over 230 additional datums, covering regions and countries on all continents around the world. You can browse this list by opening Theodolite's preferences screen via the PREFS button and tapping on the "Geodetic Datum..." button, or see them here). You can purchase the Datum Pack, which includes all datums shown in the list (as well as any future additions), by tapping the link at the bottom of the screen or by selecting any non-default datum in the list. You will be prompted to complete a one-time in-app purchase through the App Store to install the Datum Pack feature. This purchase is transferable to all of your devices running Theodolite under your App Store account (note, however, that the in-app purchase is not transferable between Theodolite and Theodolite HD, as they are separate products in the App Store and Apple doesn't allow in-app purchases to transfer between apps).

Once installed, you can select any datum that is part of the Datum Pack, and Theodolite will use the datum to convert raw GPS data into position and altitude. Most regional datums have a limited range of applicability; if you are in a position outside of that range, the datum status indicator (dot to the right of the position/altitude field at the top of the main screen) will turn red, and Theodolite's status screen (accessed by tapping any of the green/red indicators) will show "Datum error - location outside of limits". This doesn't necessarily mean that computed position and altitude are wrong, but it does suggest that the active datum is not going to provide accurate results, so another datum is likely more appropriate.

Note that mobile map content and most online mapping is based on the WGS-84 datum. Starting in Theodolite 5, any coordinates based on an alternate datum are placed at their equivalent WGS-84 position on the map screen for proper rendering over the WGS-84 based map imagery and content (map marker popups will continue to show the datum based coordinate and format even though they are pinned to the equivalent WGS-84 position on the map). You will see an overlay message in the lower right corner of the map view indicating that content is based on WGS-84.

Similarly, most online mapping services and map data formats assume the WGS-84 datum, so any map markers, map URLs, or KML files exported from Theodolite will use WGS-84 coordinates. Please keep this in mind when using an alternate datum.

Theodolite's Datum Pack has an architecture that will easily accept additional datums in future releases (at no extra charge). If you would like to use a datum that is not currently included, or have any other feedback on datums, please let us know.
US State Plane Coordinates
This optional in-app purchase adds 1927 (SPCS27) and 1983 (SPCS83) US State Plane Coordinates to Theodolite. SPCS27 has 134 zones and uses units of US survey feet. SPCS83 has 126 zones and uses units of meters, US survey feet, or standard international feet. This option costs $24.99 USD (or equivalent) through the App Store. To purchase this feature, go to Theodolite's preferences screen (PREFS button), select "Position Format", and either tap the info link at the bottom of the screen, or scroll to the bottom of the format list, select a state plane coordinate system, and tap on a zone. You can browse the list of systems and zones prior to purchase.

Note that SPCS27 is to be paired with the NAD27 datum and SPCS83 is to be paired with the NAD83 datum. You must purchase Theodolite's Datum Pack (sold separately) to enable these datums.

The State Plane Coordinates in-app purchase is transferable to all of your devices running Theodolite under your App Store account (note, however, that the in-app purchase is not transferable between Theodolite and Theodolite HD, as they are separate products in the App Store and Apple doesn't allow in-app purchases to transfer between apps).
US Mountain Summits AR Layer
This optional in-app purchase displays over 70,000 US mountain summits in Theodolite's AR view. Moving the center crosshairs over a summit shows the summit name, summit height, and distance to the summit.

Settings for this AR Layer include a selector for the max/min range of mountains to include (0 - 80 miles) and a slider that controls visibility and masking of far off summits. By adjusting the slider to the left, distant summit markers will be hidden if they are likely to be blocked from view by nearby mountains. Adjusting the slider to the right will include more and more distant summits, including those that might be blocked from view by nearby mountains. Together, the range selector and slider can be used to control how many summits are included on screen, impacting both usability and performance. On an older device, you may want to limit the range to 10 miles and keep the range slider towards the left in order to avoid hampering performance.

When viewing summits, you may wish to make use of Theodolite's compass correction mode (◀N▶ button on main screen) to properly align summit markers with summits in view. More information about compass correction mode is given here.
Image Filenames
Theodolite 6.1/6.1.1 switched to using the iOS Photos Framework to save photos and screenshots to the device camera roll, as the previous method has been deprecated. In order to continue writing extensive metadata into the image's EXIF record, Theodolite now has to take control over the image filename (previously, all photos got a generic "IMG_1234.JPG" camera roll name). This is good and bad. The good part is that we can now specify useful, human-readable filenames with a user controllable prefix (could be a project name, author name, device name, etc) and timestamp, making it easy to identify and sort files.

The bad part is that not all photo import and management software on a Mac or PC recognizes these new filenames, and you may not know if yours does until you try. Theodolite has two filename settings you can specify in its camera options (PREFS > Camera Options...). The first is a sequential file name, which is an 8-character name like "TH000163.JPG" which uses an internal file numbering sequence that Theodolite keeps track of (in this case, it's image 163). This is likely the most compatible across all platforms, as it conforms to traditional 8-character photo filename conventions for digital cameras.

The other option is to use the more advanced image title embedded in the EXIF metadata record, which has a prefix and timestamp. This would result in image filenames like "MyProjectName_Theodolite_2018.08.03_10.11.57.JPG", where "MyProjectName" is a user-specified prefix (also entered in Theodolite's camera options) and the digits on the end are a universal date and time stamp format. This format will be preferable for most people, as long as your image import and management software supports it. If you select this option but instead see random filenames like "AXQR8742.JPG", it means your software is too dumb to figure things out and you should probably change over to the sequential option (or try better software).

Regardless of how you choose to name image files, Theodolite will embed both the sequential name and the title name into the image's EXIF metadata, and you can always use that to rename the image later on using an EXIF utility such as the popular Exiftool by Phil Harvey. As an example, let's say we want to rename that random "AXQR8742.JPG" file up above to use the proper image title. To do that, we'd use the Exiftool command:

exiftool '-filename<${ObjectName}.%e' AXQR8742.JPG


If we had a bunch of images like that in a folder called "MyFolder", we could batch rename them all at once using:

exiftool '-filename<${ObjectName}.%e' MyFolder


If you instead want to use the sequential filename, do something like this:

exiftool '-filename<${ReferenceNumber}.%e' AXQR8742.JPG

or

exiftool '-filename<${ReferenceNumber}.%e' MyFolder


Finally, note that the old style "IMG_1234.JPG" camera roll filenames are still associated with Theodolite images when they are saved on your iPhone or iPad. Really good image import and management software on a Mac or PC will recognize both the image title you specified in Theodolite and the camera roll filename, and let you choose which to use when exporting later on. Unfortunately, this camera roll filename is not something Theodolite can control or embed in EXIF metadata (the name is assigned after the image leaves Theodolite and gets to the camera roll), so you will be at the mercy of your photo import and management software as to whether or not that filename sticks around. For example, the Photos app on a Mac will continue to see and use this name for photos that come over to your Mac via iCloud Photo Stream but not photos imported with a USB cable. When the camera roll filename is present, Photos on the Mac lets you control whether this name, or the photo title, is used when exporting images locally.

However Theodolite images show up on your Mac or PC, remember that you can always sort them by date to see them in the proper chronological order, regardless of how they are named. This can be important when multiple users or multiple devices are putting photos into the same folder or catalog and there can be image sequence mismatches and conflicts. Trying to organize and sort photos only by filename is an iffy process that only works when everything is just right. So consider sorting by date regardless of how images are named, and this will keep everything in the right order.
Camera Sharing
Theodolite 6.1 introduced a new camera sharing feature that allows any other app on your device to capture photos and screenshots through Theodolite, including all graphics overlays and metadata records. To use this feature, the other app needs to send a special URL request to Theodolite of the format:

theodolite://camera?app=yourapp&action=youraction

Theodolite opens, the user takes a photo, and when the photo has been processed and saved, Theodolite fires back a URL to the other app that looks like this:

yourapp://youraction?id=5778B2B7-2E3D-4806-A389-6699C41598C7/L0/001

Where that information on the end of the URL is the file ID for the photo asset in the device camera roll. The other app can then access this photo asset and get at image data and metadata, for further use.

The camera sharing function is pretty simple -- when invoked by another app, Theodolite will behave normally, but as soon as the user taps the shutter button to take a photo or screenshot, the image will be processed and then sent back to the other app. If the user leaves Theodolite before tapping the shutter button, camera sharing mode is canceled and nothing happens.


A sample app (Xcode 9 project written in Obj-C) is available that shows how to request and receive a photo from Theodolite and access the UIImage and metadata from the photo:

useTheodoliteCamera_Sample.zip
Frequently Asked Questions (FAQ)
Note: if you have a question/issue not addressed by the FAQ, please contact the developer.
The app won't launch on iOS 8 or later, or launches with a black camera view.
This means you denied permission for the app to use the camera (this is a new popup starting in iOS 8, and many people click "no" when they should click "yes"). Go to system settings > privacy > camera and correct it there. The app cannot function if it doesn't have camera access. The camera permission requirement and popup are part of iOS, not Theodolite, so please direct feedback about this to Apple.
The app won't launch after I first download it from the App Store. How can this be fixed?
First, try rebooting your device. If that doesn't solve the problem, delete the app and reinstall it (but do not delete the app after you have been using it, as you will lose any data and settings from the app). If you continue to have problems, please contact App Store support.
The app won't let me capture photos or record movies because of photo album permission. Why?
When you attempt to access the photo album from an app for the first time, you will see a popup alert from iOS asking you to give permission to the app. Many people are clicking the wrong button, which actually denies Theodolite permission to use the photo album and prevents it from saving photos or movies. To override this, go to System Settings > Privacy > Photo and give the app permission there. The photo permission requirement and popup are part of iOS, not Theodolite, so please direct feedback about this to Apple.
The app won't let me record movies due to microphone permission. Why?
When you attempt to launch an audio-visual app for the first time, you will see a popup alert from iOS asking you to give permission to use the microphone. Many people are clicking the wrong button, which actually denies Theodolite permission to use the microphone and causes movie recording to be disabled. To override this, go to System Settings > Privacy > Microphone and give the app permission there. The microphone permission requirement and popup are part of iOS, not Theodolite, so please direct feedback about this to Apple.
When I launch the app, no camera view is visible or the app quits when I try to take a photo. What is wrong?
This is a symptom of low memory. Theodolite needs as little as 20MB to launch and 70MB to process a photo, which is small compared to the 2-4GB of memory on recent model iPhones and iPads. So the low memory condition is likely caused by other apps running on your device in the background. To solve the problem, you can either force quit other apps, or simply reboot your device. If the problem happens again, you may want to determine which background app is the culprit -- it could be leaking memory or simply be using too many resources.
Does Theodolite work without access to the internet?
Most of Theodolite's features will work without access to the internet, except for online maps, e-mail export, and location services for wifi-only devices (wifi-only devices are iPads and iPods lacking GPS hardware and cellular hardware). iPhones and iPads with GPS hardware can get location data without an internet connection, however it will take longer for the on-board GPS hardware to function in a standalone mode without help from internet databases to speed refinement.

When using a GPS-enabled iOS device without an internet connection, allow extra time (tens of seconds, or a minute) for the device GPS hardware to acquire an initial position fix (this is often referred to the GPS "cold start" time). Once the initial position is locked in (and the GPS is "warmed up") subsequent position updates will behave normally.
How do photo title prefix and keywords work?
The photo title prefix and keywords inputs introduced in Theodolite 6.1 will place information in the metadata record of photos and screenshots that can be identified and used by third party software to name the image and image file, and tag the image with keywords. As an example, here's the info display in the Photos app on macOS when looking at a Theodolite photo on an attached iPhone:
Here, a title prefix of "Project_1274" was used, which Theodolite combines with a suffix and timestamp to form the photo title. You can see it is recognized by the Photos app as the title (first line at top) and file name (second line, with "jpg" file extension). In addition, note the keywords at the bottom. In Theodolite, keywords of "1274", "JCC.213.597" (a parcel ID), and "survery" were specified by the user and appended with "Theodolite" by the app. These keywords will be associated with the image file and can be used to search and sort images.

Not all photo management software is savvy to image titles and keywords, and some software will only use that info in special cases (for instance, some software will only use the title to name an image file when explicitly set to do so, otherwise a generic camera roll filename is used). But this information is hard-coded into the image metadata record, so it is always available with basic EXIF tools and scripts, just like the geo-data and other details that Theodolite embeds in the metadata record.
Does Theodolite work with third-party GPS accessories?
Yes. No special modifications are needed. Many Theodolite customers use the BadElf, Dual, and Garmin GPS modules with iPads and iPod Touches that do not include built-in GPS hardware. Please note however that while these devices can provide position and altitude data to Theodolite, they cannot provide hardware accuracy information due to limitations in iOS. So you need to read position and altitude accuracy information from those GPS modules directly, or by using the GPS manufacturer's app.
I am not getting any location data, why?
Please check System Settings under Privacy > Location Services and make sure you are allowing Theodolite to use location data. Many people turn this off without realizing it. Be aware that you need a clear line of sight to the sky to receive GPS location data, and a network connection is required for fast GPS refinement. Without a network connection, GPS location data is still available, but the initial location fix will take much longer (tens of seconds or even minutes). This behavior is characteristic of the device's location services implementation and not controlled by Theodolite itself.
I am not getting altitude data, why?
Only iPhones and cellular-capable iPad models can display altitude properly. For these devices to receive proper altitude data from GPS, they must have a clear line of sight to four satellites in the sky. Altitude may not be available if you are indoors or if your view of the sky is obscured. In marginal cases, you may receive position data but no altitude.
I am not getting azimuth/bearing data, or it's not updating.
Only the iPads and iPhones can display azimuth/bearing, since they have magnetometer (compass) hardware. iPod Touch devices do not contain a magnetometer. If your compass-equipped device is not showing compass data, or the data is not updating, your device is probably being affected by electromagnetic interference. The magnetometer is susceptible to interference inside cars, near metal objects/structures, or near electronic equipment. Try moving to a different location, and wave the device in a figure eight motion to recalibrate the magnetometer.
I see ERR in my compass display.
If you see that, it means that at some point in the past (could have been years ago) you turned off compass calibration in iOS Settings. That will prevent the device's compass from computing true bearing from your local magnetic declination. To turn it back on, go to:

iOS Settings > Privacy > Location Services > System Services (way at the bottom)

Then flip the switch for "Compass Calibration" to on. That should solve the problem. It may take a couple seconds for the compass sensor to start delivering the new data to the app.
Why doesn't Theodolite make a catalog, map, or log file of photos so that we know their locations?
That might have been needed in the old days, in which case it could be a chore to keep the catalog information synced up and associated with photos. If the catalog file got separated from photos, the whole system would break. Nowadays, we avoid this issue by directly embedding metadata into the image file itself. This metadata includes date, time, location, camera settings, and other geo-data recorded by Theodolite when you take a photo or screenshot. This makes every Theodolite image file a self-contained data record, and the data will always be a part of the image and stay with the image unless you take special steps to strip it out.

Forget the notion of cataloging photos with some separate method or file, and take advantage of the data record built in to every Theodolite image. Most photo management and GIS software will automatically access this information for you and use it to catalog and manage your images without any extra effort.

If you still find it necessary to make a catalog of Theodolite image files, the free Exiftool utility by Phil Harvey can take a folder of Theodolite images on a Mac or PC and generate XML, CSV, KML, ... catalog files. You can also use it to make custom catalog formats.
How can I access EXIF metadata within Theodolite images?
A lot of mapping and GIS software will be able to tap into this data, or you could use the free Exiftool utility by Phil Harvey on a computer. An example command is:

exiftool -csv -DateTimeOriginal -GPSImgDirection -GPSLatitude -GPSLongitude -UserComment myfolder > out.csv

Where "myfolder" is a folder with your images and "out.csv" is a CSV file that will be generated. This produces a CSV file that looks like this (from only two images in our test folder):

SourceFile,CreateDate,GPSImgDirection,GPSLatitude,GPSLongitude,UserComment
myfolder/IMG_3133.JPG,2019:11:16 09:55:10,231.1912384,"37 deg 52' 5.21"" N","78 deg 51' 23.87"" W",Test Comment 123
myfolder/IMG_3134.JPG,2019:11:16 09:55:23,237.2256362,"37 deg 52' 5.21"" N","78 deg 51' 23.87"" W",Test Comment 234

There is much more information available in the photo metadata, so you can pick out exactly what you want and adjust the ExifTool command accordingly.
UTM coordinates are wrong for my location.
There are two UTM formats, differing only by the letter displayed after the zone. Standard UTM uses "N" or "S" to denote the hemisphere. Banded UTM (called UTM-B in Theodolite's position format list) uses MGRS latitude bands (A-Z, omitting I and O) after the zone. You can choose either format in Theodolite. For more information on UTM, see this Wikipedia article: UTM coordinate system
Is it possible to only use the gyro for azimuth measurement on devices that do not contain a compass?
Unfortunately, gyro-derived azimuth is not robust enough to be accurate by itself, due to gyro drift. After setting a North reference, motion and rotation of the device would cause it to drift from the reference over time, and eventually become totally inaccurate. This can occur in as little as one 360 degree rotation, resulting in errors of 30-60 degrees or more. Therefore, Theodolite eschews this approach in favor of combined gyro-compass fusion. The fusion algorithm in Theodolite gives the best of both worlds, providing fast response and accurate measurement from the gyro during dynamic use of the device, with periodic corrections from the magnetometer to eliminate drift.
I don't see zero elevation and/or horizontal angle when holding the phone perfectly level.
Try running the calibration by pressing the "CAL" button. Aim/position the iPhone to align with a known horizontal reference at zero elevation angle, and the calibration process will associate this with zero elevation and pitch. This mechanical-optical procedure corrects out offsets in the gyro, accelerometer, and camera hardware. Note: only attempt calibration if you have a proper fixture to align and position your device and a level elevation/horizon reference accurate to less than 0.1 degrees.
Why isn't calibration simpler?
Many apps, such as bubble level apps and g-meter apps, only need to calibrate the device accelerometer and gyro relative to the case. In those instances, it's sufficient to level the device case when calibrating. In contrast, Theodolite needs to calibrate the acceleromater and gyro relative to the camera lens view, since that is how the app is used. Thus, "optical" references for level elevation and horizon angles are required. This process corrects for mounting errors in the accelerometer, gyro, and camera lens.
The compass / position / altitude data seems way off, why?
Tap the various green/red status icons shown on the screen to see the hardware status. Accuracy of data received from the device's hardware will be shown. The app's accuracy is limited by what the hardware can provide. For good GPS data, make sure you have a clear line of sight to the sky. For good compass data, be sure you are away from any sources of electromagnetic interference. Note that the iPhone corrects altitude data based on an ellipsoidal model of the Earth's surface, so altitude is only approximate in most cases. This is an inherent limitation of the device and SDK.
Latitude/longitude coordinates seem wrong for my location; how are they formatted?
Position coordinates can be displayed in several ways in the app. Some of the lat/lon position formats in Theodolite use an "absolute" reference system, with North latitude and East longitude taken as positive directions. Other lat/lon options use a relative coordinate system, expressing positive latitudes as North, negative latitudes as South, positive longitudes as East, and negative longitudes as West.
What GPS datum is used in the app?
The GPS and location hardware in all iOS devices (and most consumer GPS devices) defaults to the WGS-84 ellipsoid. Theodolite 3.2 and later offer an optional Datum Pack that includes over 230 additional datums that can be used in the app.
The app's compass direction does not agree with that of a handheld compass, why?
First of all, make sure the real compass is not near your device, as it can interfere with the compass needle and throw it off. Then make sure you have switched Theodolite to display magnetic north so that it will be consistent with a real compass. For accuracy of the device's compass, tap the status icon shown to the left of the azimuth/bearing display. The iPhone compass accuracy is generally in the range of 5 to 10 degrees, but can be as poor as 20 or 30 degrees (or worse) if there is electromagnetic interference.
The app's compass seems stuck and the TRUE indicator on the screen is marked in red
Go into your device's settings, under Privacy > Location Services. Scroll to the bottom, and select "System Services". Make sure that the "Compass Calibration" option is turned on. This is required in order for Theodolite to get magnetic declination information from GPS, which is used to compute a TRUE direction. If you have this turned off, or if you are not allowing access to location services, only MAGNETIC direction can be used in Theodolite.
Do saved photos contain EXIF metadata?
Yes. iOS 4.1 was the first OS release to allow embedding of geo-tag EXIF metadata when third party apps save photos to the device photo album. Versions 2.2 and later of Theodolite support this feature, recording position, altitude, bearing, angles, and user notes in the EXIF metadata. Theodolite 5 adds data for elevation and horizon angles to the EXIF record, as plain text in the TIFF "image description" field and as XML data in the EXIF "maker note" field. Note: images exported from the app via e-mail do not contain EXIF metadata since they are never written as files on the device.
Do saved movies contain EXIF metadata?
Due to limitations in the iOS SDK, this feature is not currently available, but we hope to add it in a future version of Theodolite.
I don't see a MAIL button on my screen.
In order for Theodolite to enable e-mail export, there must be active e-mail accounts setup on your device in iOS system settings (using third-party e-mail apps doesn't count -- you must have e-mail setup in iOS system settings). If you do not have any accounts, Theodolite disables the e-mail export feature and hides the MAIL button. You can enable this feature by setting up an e-mail account, and then force-quit and relaunch Theodolite.
Why aren't screen movies at full retina display resolution on some devices?
It turns out that some devices don't actually have the hardware video encoding capability to make movies at full screen resolution (which is larger than typical HD formats). So on these devices, Theodolite produces screen movies at 50% scale resolution.
Why doesn't the screen flip around when I put the device in different orientations?
Because Theodolite is setup to measure compound angles in 3D, a single reference orientation must be used, otherwise we'd never be able to measure angles past about 40 degrees in any direction without the screen flipping around. Theodolite defaults to the landscape-right orientation for iOS devices, which is Apple's recommended default orientation to be used in situations where only a single landscape orientation is supported. Why? Well, this orientation puts the camera on the top edge of the device (preferable for photography and AR), it puts the home button / home indicator on the right, and it puts the screen notch on the left. As a result, this is the preferred orientation for accessories that follow Apple guidelines, including holsters, tripod mounts, stands, smart covers, etc. If you need the ability to change device orientation but don't need 3D angle measurement and survey capabilities, check out Theodolite's sister app Nav Camera
Why can't we use the volume buttons to take pictures?
Apple has never approved this feature for third-party apps (see App Store review guidelines 2.5.9: Apps that alter or disable the functions of standard switches, such as the Volume Up/Down and Ring/Silent switches, or other native user interface elements or behaviors will be rejected).

While some apps manage to sneak the feature past Apple review, others are rejected and not allowed to go on sale in the App Store. We do not plan to implement this feature and risk rejection from the App Store, but will gladly implement it if Apple approves the feature for third-party apps at some point in the future.
Can you send me a PDF of this user manual?
For offline viewing of this user manual on an iOS device, tap the action button in Safari's toolbar, then select "Add to Reading List". That will create a local copy of this user manual that you can view at any time from within Safari's Reading List, with or without an internet connection. For more info on Safari's Reading List feature, see this Apple Support article. For offline viewing on a Mac or PC, select Print from your web browser's File menu, then select a PDF file as your destination. On Mac, this is done with the PDF popup in the lower left corner of the print dialog. On Windows, select "Microsoft Print to PDF" as your printer.
Something bad happened to my device, and I need to re-download Theodolite. Do I have to pay again? What about my in-app purchases?
Once you purchase Theodolite, you are able to install it on up to 5 devices under your Apple ID. You can download Theodolite again at any time without additional cost. Just go to the App Store app on your device and look in the Updates > Purchased section to download the app.

The datum pack, team tracking, mountain summits, and state plane coordinate in-app purchases are non-consumable, and can be restored at any time, or installed on up to 5 devices under your Apple ID. Please access the particular feature in Theodolite, ask to "learn more", and then tap the "Restore" button.

Map tile credit in-app purchases for Outdoors maps are consumable in-app purchases, and cannot be shared among devices. However, Theodolite uses a couple tricks to help you restore them from a data loss or when transferring over to a new device. To do this, you must make use of device backups (to a PC/Mac or iCloud) and let Theodolite use iCloud (see iOS system settings to enable that, under Documents & Data in iOS 7/8 or iCloud Drive in iOS 9/10/11 and later). You would first restore Theodolite and it's data/settings from backup, and then the app will detect the change and attempt to connect with iCloud to access your map tile credits.
I bought Theodolite HD but it won't install on my iPhone. Why?
Theodolite HD is an iPad-specific app with iPad-specific optimizations (in general, apps with "HD" in the name are iPad-only). It cannot run on iPhones. Theodolite is offered in two device-specific versions to keep pricing lower and app size smaller, since not everyone owns both types of devices or would want to pay for a more expensive universal app.
I bought Theodolite. It installs and runs OK on my iPad, but shows up in 1X/2X screen emulation mode like an iPhone app. Why?
Theodolite is an iPhone app, not an iPad app or a combined universal app. It will run on iPads, but will be lacking iPad-specific optimizations and camera/screen calibrations. If you want the full iPad experience, you can purchase Theodolite HD for your iPad. Theodolite is offered in two device-specific versions to keep pricing lower and app size smaller, since not everyone owns both types of devices.
I own an iPhone and an iPad. Why do I have to pay for the app twice?
We offer the app as two separate lower-priced products -- one for iPhone/iPod (Theodolite) and one for iPad (Theodolite HD) -- since not all customers own both devices or would want to pay for a more expensive universal app. If you do own both device types and you want to purchase both versions of Theodolite, you will be paying the same amount we'd charge for a universal iPhone/iPad app if we offered one.
Why do I have to buy the same in-app purchases (like the datum pack) for all of the apps in your bundles?
While Apple allows developers to bundle apps together at a discount, they do not allow developers to bundle in-app purchases or to even share in-app purchases across apps. We are glad to be able to offer discount bundle pricing on our apps, but it's not possible to do this with in-app purchases. Please complain to Apple if you don't like this policy.
Why are Outdoors Maps priced by the tile? Why not a subscription?
When developing and setting up this feature, it became apparent that per-tile pricing made the most sense, since that is how we are billed by the map data provider. With this approach, you pay for exactly what you use, without any time limits or commitments. A light user can spend as little as $0.99 USD (or equivalent) for their maps, while a heavy user can pay more to cover expanded usage. It ends up being fair for everyone. With a subscription, light users end up paying more to subsidize heavy users, which isn't fair. On top of that, subscription management looked like a big hassle, requiring customers to opt-in to an online tracking system with some personal information for proper access. We really don't want or need to know your personal information just to grant you access to some great maps.
Do you plan to offer Theodolite for Android? Windows? Blackberry?
While we'd love to support customers on all platforms, it costs well over $100K USD to port a complex app like Theodolite, and even more to support it on platforms that have zillions of device specs and wildly inconsistent OS versions in distribution. If you don't see Theodolite available for your platform, it means we can't support that platform without losing money. Sometimes maintaining a healthy business comes down to focus and learning when to say no. Right now iOS is our focus.
Contact Info
If you need assistance or have feedback, please contact:

dev@hunter.pairsite.com

Feature requests, comments, and suggestions are welcome. Many of the features in Theodolite started as customer requests, so your input is valuable.
App Store Reviews
If you like Theodolite and find it useful, please leave a review on the App Store. Long term development of this app depends on having a strong, involved customer base. App Store reviews help establish the app and improve sales, which in turn provides financial support for continued development. Please consider leaving a review. Customers who have written reviews for previous versions of Theodolite can update/revise their reviews after downloading new versions of the app. Your support is greatly appreciated!
About Theodolite
Developed by Dr. Craig A. Hunter
Copyright © 2009-2023
Hunter Research and Technology LLC