Theodolite User Manual
Theodolite / Theodolite HD
User Manual

Updated Februry 6, 2017 - Version 5.0

Copyright © 2009-2017
Hunter Research and Technology LLC

THIS USER MANUAL IS OUT OF DATE -- PLEASE SEE:
http://hunter.pairsite.com/mobile/theodolite/help/latest.html
Quick Links
Main Screen Functions
This section discusses some of the buttons on Theodolite's main screen.
PREF (Preferences)
Tap the "PREF" 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), geodetic datums, and position format. 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, and optional US State Plane Coordinates. 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.
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.
LENS
This button toggles colored lens filters over the screen, which may be helpful to preserve night vision or improve usability in low light situations. Available colors are red, green, gold, and gray. The same button toggles the display back to normal.
ZOOM
This button toggles the zoom level of Theodolite's main display between 1X, 2X, and 4X.
CAMERA
This button is used to take photos and screenshots or record movies. The app's camera mode can be changed via the PREF button.
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 via e-mail, 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, altitude, datum code, heading (deg), heading (mils), elevation angle, and horizon angle (for a list of datum codes and descriptions, see here). E-mail export of the log also includes a KML 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).
Reticles
Tap the center of the screen to cycle between the 10 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 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 (such as the iPhone 3GS), 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.
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, using a proprietary database that we maintain in-house. Every new model of iOS device is tested on an optical rig to determine its lens and camera specifications, and then Theodolite is updated to properly support the new device. Theodolite's rangefinder capabilities are unique; we know of no other developer that goes to this level of effort (most simply render "pretend" rangefinder graphics on screen).

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 of the rings will change with Theodolite's zoom level.

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 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.

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.
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 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 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 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. Starting with Theodolite 5, the accuracy screen is updated in realtime while open.

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 15-25 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.
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.


New in Theodolite 5 is 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 screen.
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, or USNG. For readability, you can use spaces between text blocks when entering MGRS, UTM, UTM-B, 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.
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.
Offline Outdoors Maps
Theodolite 5 introduces new 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 5,000, 10,000, 20,000, .... up to 200,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 5,000 tiles, with intermediate price tiers and increasing discounts the more tiles you purchase.

Note: Outdoors map tile credits are a consumable in-app purchase, which means iTunes installs them on a per-device basis and does not share them between devices in your iTunes account. You must add map tile credits to each device separately, if desired. In addition, iTunes 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 iTunes. 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).

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 $0.99 USD (or equivalent) through the iTunes 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 iTunes 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 iTunes account (note, however, that the in-app purchase is not transferable between Theodolite and Theodolite HD, as they are separate products in iTunes 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.

Team tracking is a new and evolving feature in Theodolite, and users are encouraged to provide feedback 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 iTunes 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 PREF 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 iTunes App Store to install the Datum Pack feature. This purchase is transferable to all of your devices running Theodolite under your iTunes account (note, however, that the in-app purchase is not transferable between Theodolite and Theodolite HD, as they are separate products in iTunes 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 on Theodolite's main screen (third dot to the right of the POSITION-ALTITUDE-TIME label) 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. This option costs $19.99 USD (or equivalent) through the iTunes App Store. To purchase this feature, go to Theodolite's preferences screen (PREF 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 iTunes account (note, however, that the in-app purchase is not transferable between Theodolite and Theodolite HD, as they are separate products in iTunes and Apple doesn't allow in-app purchases to transfer between apps).
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/9/10, 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 iTunes. 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 iTunes 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 512-2048MB of memory on iPhones, iPads, and iPods. 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 3G/4G 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 to acquire an initial position fix. Once the initial position is locked in, subsequent position updates will behave normally.
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.
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 (3G/4G) data 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.
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 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.
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 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.
Why does it take so long to save photos?
On newer iOS devices, photo saves are fast and you won't notice any delay. On older devices, it takes anywhere from 1-2 seconds to process and save the image to your photo album depending on your device and how large of a photo it takes. This work is 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 can continue after you leave the app.
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 retina iPad and iPad mini models and iPhone 6+/6S+/7+?
It turns out that these 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 cases where only a single landscape orientation is supported. This orientation puts the camera on the top edge of the device and is the preferred orientation for device accessories that follow Apple guidelines, including holsters, tripod mounts, stands, smart covers, etc.
Why can't we use the volume buttons to take pictures?
Apple has never approved this feature for third-party apps. While some apps manage to sneak the feature past Apple review, others are rejected and not allowed to go on sale in iTunes. We do not plan to implement this feature and risk rejection from iTunes, 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.
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, 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). 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.
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?
Well, you don't "have" to do anything. But we're not trying to rip you off. 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.
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 -- we will gladly offer these additional types of discounts if they are ever possible.
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 a lot of 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.
iTunes App Reviews
If you like Theodolite and find it useful, please leave a review on iTunes. Long term development of this app depends on having a strong, involved customer base. iTunes 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-2017
Hunter Research and Technology LLC