Theodolite
Documentation / Help / FAQ
Updated April 24, 2012 - Version 2.7

THIS USER MANUAL IS OUT OF DATE -- PLEASE SEE:
http://hunter.pairsite.com/mobile/theodolite/help/latest.html
Settings
Tap the "PREF" button in the upper left corner of the screen. The Free version of Theodolite includes settings for the compass and units, and a link to this help page. The Pro and HD versions add camera/image options, options to display angles in degrees or percent grade, and position format settings.
"ZERO" Button (HD and Pro versions only)
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.
"CAL" Button (HD and Pro versions only)
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.
Optical Rangefinder (HD and Pro versions only)
Version 1.2 introduced an optical rangefinder feature that allows you to quickly estimate distance to objects and landmarks, provided you know some dimension of the object in view. To bring up the rangefinder reticle, tap the center of the screen until it appears, or select the ring reticle in preferences. Default rings are 2x, 3x, 4x, 6x, 8x, and 16x, which indicate scale factors between object size (ring diameter) and distance to the object. 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.

Theodolite Pro 1.3 added an additional rangefinder by placing mil-dot markings on the center crosshair reticle. Dot spacings are 20 mils at 1X zoom, 10 mils at 2X zoom, and 5 mils at 4X zoom.

Theodolite 2.3 includes a mil-ring rangefinder. It functions like the scale factor rings, but instead uses scales of 100-600 mils.
A-B Calculator (HD and Pro versions only)
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-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.
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.
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
New in Theodolite 2.6, 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.
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 (iPad, iPhone 3GS, iPhone 4, and iPhone 4S 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 compas 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.
"LOG" Button (HD and Pro versions only)
Tapping this button brings up the data logging popup, with buttons to add a data record, clear the data log, export the data log via e-mail, and copy the data log to the system-wide clipboard (where it can be pasted into other applications). The data log is formatted with a header and a space-delimited line for each data record. E-mail export of the log also includes a KML file with all data records.
"MAIL" Button (HD and Pro versions only)
Tapping this button generates an e-mail containing current data, a Google maps URL to the current location, a screenshot, and a KML file (usable in Google Earth, AutoCAD, and other applications).
"LENS" Button (HD and Pro versions only)
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.
Sharing Map Markers (HD and Pro versions only)
Theodolite 2.7 introduced an exciting new feature -- 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 "Share" button on the marker's popup. 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 Theodolite Pro or Theodolite HD installed (version 2.7 or later). 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 name is used, 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.
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 after I 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. This is an iTunes issue, and not specific to Theodolite.
When I launch the app, no camera view is visible. What is wrong?
This is a symptom of low memory. Theodolite needs as little as 10MB to launch, which is small compared to the 128-512MB 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.
I am not getting any location data, why?
Please check the Settings App under "General > 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 the iPad 1 3G, iPad 2 3G, and iPad 3 4G models and iPhone 3G, 3GS, 4, and 4S models can display altitude. 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 iPad 2, iPad 3, iPhone 3GS, and iPhone 4 can display azimuth/bearing, since they have magnetometer (compass) hardware. 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.
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 (Pro and HD versions only). 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.
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 a very simple 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. The first two options on the left of the "Position Format" control in preferences (HD and Pro versions only) are for an "absolute" reference system, with North latitude and East longitude taken as positive directions. The next two options use a relative coordinate system, expressing positive latitudes as North, negative latitudes as South, positive longitudes as East, and negative longitudes as West.
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 2 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 does not report proper TRUE direction.
If running iOS 5, go into your device's settings, under "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, only MAGNETIC direction can be used in Theodolite.
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 screen or case. In those instances, it's sufficient to level the device screen or 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.
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, and user notes in the EXIF metadata. Note: images exported from the app via e-mail do not contain EXIF metadata.
Why does it take so long to save photos?
When taking photos from the app, it takes anywhere from 1-10 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 in iOS 4 (iPad 2,iPhone 3GS and 4, and iPod Touch 4), image saves can continue after you leave the app. On devices that don't support multitasking, do not quit the app if an image save is in progress, otherwise the image won't appear in the photo album.
Contact Info
If you need assistance or have feedback, please contact:

dev@hunter.pairsite.com

Feature requests, comments, and suggestions are welcome. Most of the features added to updated versions of Theodolite started as customer requests, so 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 dowloading new versions of the app. Thanks for your support!
About Theodolite
Developed by Dr. Craig A. Hunter
Copyright © 2009-2012
Hunter Research and Technology LLC