Theodolite User Manual
Theodolite
User Manual

Updated September 18, 2013 - Version 3.2

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
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), datums, and position format. This 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 changes via the PREF button.
LOG
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
Tapping this button generates an e-mail containing current data, URLs to open the current location in Theodolite, Gaia GPS, and Google Maps, a screenshot, and a KML file (usable in Google Earth, AutoCAD, and other applications).
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 watermark the image with a center crosshairs, a data stamp showing date, time, geo-data, and zoom level, and a custom user-entered note. The watermark 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.
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 a watermark 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).

Warning: 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 2-4 seconds for every 1 second of recorded video on a typical device. This processing overhead can stretch to as much as 15-25 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.

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. 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 be in 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 be in 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 be in 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 (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.
Hardware/Sensor Status and Accuracy
To see the current reported accuracy of hardware and sensors, tap any of the green/red status indicators on the screen. The accuracy of position, altitude, elevation/horizon, and azimuth measurements in Theodolite are determined by the hardware 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.1 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.


Tap the magnifying glass button on the map screen to search for a location and center it in the map view. You can directly enter general text inquiries, street addresses, or comma- or space-delimited latitude/longitude coordinates. To lookup MGRS coordinates, prefix the MGRS string with mgrs=. Use a utm= prefix to lookup UTM coordinates, and a utmb= prefix to lookup banded UTM coordinates. These prefixes will help Theodolite improve speed and accuracy of search results. For readability, you can use spaces between text blocks when entering MGRS, UTM, or UTM-B 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 "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 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 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.

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. Marker names must be percent-escaped.

For additional questions about Theodolite URL sharing, please contact the developer.
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 (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 in 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, the in-app purchase is not transferable between Theodolite and Theodolite HD, as they are separate products in iTunes). Currently, no additional usage charges 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 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 where 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
Theodolite 3.2 introduced an optional Datum Pack, which adds over 220 new 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 (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 220 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. You can purchase the Datum Pack, which includes all datums shown in the list (as well as any future additions), 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).

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 is NO-GO. 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.

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.
Frequently Asked Questions (FAQ)
Note: if you have a question/issue not addressed by the FAQ, please contact the developer.
My pictures are not being saved to the photo album in iOS 6 or 7.
When you attempt to access the photo album from an app in iOS 6 or 7 for the first time, you will see a popup alert from iOS asking you to give permissions to the app. Many people are clicking the wrong button, which actually denies Theodolite permission to use the photo album. To correct this, go to System Settings > Privacy > Photo, and give Theodolite permission there. The photo permission popup is from iOS, not Theodolite, so please direct any feedback about this feature to Apple.
Theodolite 3.2 quits on launch with iOS 7.
When you attempt to launch an audio-visual app in iOS 7 for the first time, you will see a popup alert from iOS asking you to give permissions to use the microphone. Many people are clicking the wrong button, which actually denies Theodolite permission to use the microphone and causes the app to quit when it sets up the movie recording feature. To correct this, go to System Settings > Privacy > Microphone, and give Theodolite permission there. The microphone popup is from iOS, not Theodolite, so please direct any feedback about this feature to Apple. We will update the app shortly to avoid the quitting problem, but note that denying permission to use the microphone will disable movie recording in the app.
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-1024MB 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 with the BadElf GPS accessory?
Yes, in fact any location-aware app will work with the BadElf accessory -- no special modifications are needed. Many Theodolite customers use the BadElf accessory on iPads and iPod Touches that do not include built-in GPS hardware.
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, 4S, and 5 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, 4, 4S, and 5 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.
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.
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 220 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
If running iOS 5 or 6, 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, or if you are not allowing access to location services, 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 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.
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.
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?
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, image saves can continue after you leave the app.
Why aren't screen movies at full retina display resolution on an iPad 3?
It turns out that the iPad 3 doesn't actually have the hardware video encoding capability to make movies at retina screen resolution. So on this device, Theodolite produces screen movies at 1024x768 (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 45 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 orientation is supported. This orientation is the preferred orientation for device accessories that follow Apple guidelines, including holsters, mounts, 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.
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. Thanks for your support!
About Theodolite
Developed by Dr. Craig A. Hunter
Copyright © 2009-2013
Hunter Research and Technology LLC