Theodolite

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

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

Theodo olite 2.3 includes a mil-ring g rangefinder. It functions like l the scale factor rings, but instead uses scales of 100-600 mils.

A-B Calculator C (HD ( and Pro o versions only)

These functions calculate information from two observation n readings, A and B. Theod dolite will remem mber data from m both points if you leave the t app before e completing a calculation. For long distanc ce measurem ments, you can n record data at point A, leave the app, travel to poin nt B, and reactiv vate the app to o record data and proceed d with a calculation. A-B functions canno ot be used when Zero Z Ref mod de is active. A-B Di istance/Head ding Tap the e A button at location A, th hen travel to lo ocation B and d tap the B bu utton. Theodo olite will calcula ate the distanc ce and headin ng between th he two points s (using their latitude/longit l tude coordin nates). Be mindful of the Cell/GPS C position accuracy y (shown by ta apping the gre een/red status icons on o the screen) when using this option, as a it affects th he accuracy of o the result. The T greater th he distanc ce between points A and B relative to th he position ac ccuracy, the better b the resu ults will be. Upon completion, c points A and B will be show wn on the map p along with th he bearing lin ne between th he two points. t from A-B Elevation E Ang gles Height Aim at the bottom of the object to o be measure ed and tap the e A button, the en aim at the top of the object and tap B. Th heodolite will ask you to inp put the horizo ontal distance e to the object t, then it will calcula ate the object''s approximat te height base ed on the cha ange in elevat tion angle bet tween A and B. This is useful when you can easily make or es stimate horizo ontal measure ements but no ot vertical one es. You do o not need to be on level ground for this s measurement.

Distan nce from A-B B Elevation Angles A Similar r to above, bu ut solves for horizontal h dist tance assuming the object''s height is kn nown. Aim at the bot ttom of the ob bject to be me easured and tap t the A butt ton, then aim at the top of the t object and d tap B. Theodolite T wi ill ask you to input the heig ght of the obje ect, then it wil ll calculate the e approximat te distanc ce to the object based on the t change in elevation angle between A and B. This s is useful to calcula ate range/distance to objec cts and landm marks with kno own height. You Y do not nee ed to be on level ground for this s measuremen nt.

Alterna ately, you can n use your hei ight to estima ate distance to o an object as s shown below w -- aim at the bottom m of a far off object for point A, then aim level (zero elevation angle e) for point B. . Then input your ey ye height, or more m specific cally, the height of your dev vice. Theodolite will calcula ate the approx ximate distanc ce to the obje ect. This meas surement doe es require tha at the user and d object are on o level ground.

Distan nce and Heig ght from A-B Elevation An ngles New in n Theodolite 2.6, 2 this metho od calculates s distance and d height simulataneously, though t accura acy is reduced d from the me ethods discussed above. In n this case, th he device heig ght is used as s the refe erence input along with the e A and B ele evation angles s. This measu urement requires that the user an nd object are on level grou und.

A-B De elta Angles Theodo olite will calcu ulate the difference in elevation, horizon n, and azimut th (if available e) angles betwee en points A an nd B. Useful when w you nee ed to know the relative ang gles between two objects from a common pos sition. T n (iPad, iPho one 3GS, iPho one 4, and iP Phone 4S only) Point C from A-B Triangulation From lo ocation A, aim m at an object t or landmark k in the distance and tap th he A button. Then T travel to location B, aim at th he same objec ct, and tap the e B button. Th heodolite use es the latitude e/longitude position and azimuth recorded at t points A and d B to triangulate point C, the t approxima ate location of o the obj ject/landmark k you were aim ming at. It also provides dis stances betw ween the three e points. Upon n comple etion, points A, A B, and C will w be shown on o the map along with bea aring lines bet tween the thre ee points. Be min ndful of the Ce ell/GPS positi ion accuracy and compass s accuracy (shown by tapp ping the green/r red status ico ons on the scr reen) when us sing this optio on, as they gr reatly affect th he accuracy of o the tria angulated resu ult. The great ter the distanc ce between points p A and B relative to th he position accura acy, the better r results will be. b

Note th hat there are several cases s in which tria angulation can nnot occur: if points A and B are the same, if bearings fro om A and B do d not intersect, or if the be earings from A and B do no ot form a triangle e. For the bes st results, the angle betwee en azimuth A and B (ie, the angle at po oint C) should be at le east twice as big as the co ompas accura acy and no lar rger than about 160 degree es. Show A-B Points on o Map After re ecording poin nts A and B, th hey will both be b shown on the Map.

"LOG G" Button (H HD and Pro o versions only) o

Tappin ng this button brings up the e data logging g popup, with buttons to ad dd a data reco ord, clear the data lo og, export the data log via e-mail, e and co opy the data log to the sys stem-wide clip pboard (where e it can be e pasted into other o applicat tions). The da ata log is form matted with a header h and a spacedelimited line for each data recor rd. E-mail exp port of the log g also includes s a KML file with w all data records s.

"MAIL L" Button (HD and Pro o versions only)

Tappin ng this button generates an n e-mail conta aining current t data, a Goog gle maps URL L to the curre ent location, a screensh hot, and a KM ML file (usable e in Google Ea arth, AutoCAD, and other applications).

"LENS S" Button (HD ( and Pr ro versions s only)

This bu utton toggles colored lens filters over the screen, which may be he elpful to prese erve night vision or o improve us sability in low light situation ns. Available colors are red d, green, gold d, and gray. The T same button b toggles s the display back to normal.

Sharing Map Ma arkers (HD and a Pro ve ersions only y)

Theodo olite 2.7 introd duced an exc citing new fea ature -- the ab bility to share map markers s with other users of o the app via a SMS text me essaging and e-mail. To ac ccess this fea ature, tap any y marker show wn on the built-in map, and then tap the "Share" button b on the marker's pop pup. Data sha ared from l markers incl ludes position n and marker name. Data shared s from A or B points (created with h normal Theodo olite's A-B calculator) inclu ude position, altitude, a azimuth, elevation n angle, and horizon h angle. points for dis This allows users to o share A-B measurement m stributed and team t calculat tions. For ple, users could aim at a co ommon landm mark from two o different pos sitions (one de esignated A, examp the oth her designated d B), and then n share that data d to compu ute the positio on (point C) of o the landmar rk. Or use ers at different t positions could share dat ta to compute e the distance e and heading g between the eir positions. When sharing a map marker via SMS text me essage, a spe ecial data URL L is transmitte ed to the recipient. When sha aring via e-ma ail, a formatted message is s sent contain ning a link with h an embedded data URL. These sp pecial URLs will w be active and a recognize ed on any iOS S device with Theodolite Pro P or Theodolite HD installed (versio on 2.7 or later). When the recipient taps s the URL or link, Theodoli ite will ope en and import t the marker. Map markers m will be e imported dir rectly, with the e option to ed dit the marker r name (by de efault, the origina al name is use ed, appended d with the nam me of the send der's device). A-B markers s will open wit th an opti ion to import the t point as A or B, or as a simple map marker (whic ch only uses position). p When importi ing as A or B, , the new poin nt will overwri ite any existin ng A or B poin nts on the rec ceiving device e.

Frequ uently Aske ed Question ns (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