9/17/13
TPE for iOS
© Crookneck Consulting LLC, 2010 – 2013.
All rights reserved
photoEphemeris.com
Write a review
E-mail support
Support page
Tutorials
Contents
† new or updated in version 2.5
Overview
Quick Help
Basics
Pages
Dates
Locations
Settings †
Using TPE Offline
Using Offline Maps
Support
Credits
Overview
The Photographer's Ephemeris (TPE) provides tools to help with the planning of natural light photography,
particularly landscapes and cityscapes.
Quick Help
Shake your device to view overlay help guides for the Map, Dates, and Locations tabs.
Basics
The map always displays a red pin (the "primary" pin) marking the location for which calculations of
rise/set times are performed. You can drop the pin in the centre of the map (see Drop Pin below), lock
to the centre coordinates, or drag and drop the pin to the exact location you want.
To move the map pin, touch once to select (coordinates will be displayed), then touch and hold briefly before
dragging. Position the cross-hairs over your target location and then release. Avoid moving the pin too
quickly.
Lines are drawn outward from the primary pin showing the direction of sun/moon rise/set for the selected
date, and sun/moon position for the selected time of day:
file://localhost/Users/stephen/Documents/Development/iPhone/TPE/web/iTPEHelp.html
1/9
9/17/13
TPE for iOS
Sunrise
Sunset
Moonrise
Moonset
Sun position
Moon position
Note: not all lines are displayed for all locations and dates. Moonrise or moonset does not occur on every
date. Additionally, in high latitudes the sun or moon may remain above or below the horizon for many days at
a time.
Depending on the selected page (see below), the following buttons appear at the top right of the map:
Search prompts you to enter the name of a place to search for (requires data connection) and
repositions the map to the best location match.
Go to current location will move the primary pin to the current position detected by your
device. The button remains active until a position of better than 100m/328ft accuracy is
found, or until you cancel by touching the button again. Location services must be enabled,
and TPE must be authorized for this function to be available.
Drop/lock pin repositions the primary pin to the current centre of the map, no
matter where it was previously. If the pin is already centered and the button is
touched again, a reticle (cross-hairs) is shown indicating the centre of the map. On
moving the map, the primary pin will be placed at the centre coordinates when locked. Touch the button
again to unlock.
Status indicators are shown at the top left corner of the map and have the following meanings:
Time zone unknown
Time zone OK, elevation unknown
Time zone and elevation OK
If you are in an area with no or poor data connectivity, the app will calculate sunrise/sunset times, etc., based
on last known time zone (or any override time zone you set), and will assume the location is at sea level. If
the status indicator is red, double check that an appropriate time zone has been specified for your location.
Unknown elevation can result in small differences in calculated rise/set times and directions.
If your device includes the required hardware, you can enable a built-in compass by touching the
compass outline at the top left of the map. The red arrow indicates north. The large value displays
bearing relative to true north. The smaller value is bearing relative to magnetic north. Rotate your
device a few times in a figure-of-eight motion to obtain the best reading. Touch the dial again to
disable the compass (which can help conserve battery life).
Location services must be enabled, and TPE must be authorized for true bearing to be available. Note: the
built-in compass can be significantly less accurate than the bearings and azimuths calculated by the app. Use a
precision field compass for optimal results.
Pages
Below the map, different pages can be selected showing different information and functions. Swipe left or
right, or touch the page control to change the current page. The Rise/Set information page (page 1) is the
default upon starting the app. Swipe the pages to access additional information and functionality.
Useful shortcuts
file://localhost/Users/stephen/Documents/Development/iPhone/TPE/web/iTPEHelp.html
2/9
9/17/13
TPE for iOS
As a shortcut, double-tapping on a page will change the current date. Double-tap on the right to advance to
the next day, or on the left to go to the previous day.
Double tapping with two fingers anywhere in a page will return to page 1, Rise/Set information.
1: Rise/Set information (default page)
The time and direction (azimuth) of sunrise, sunset, moonrise and moonset are shown. Remember, sun/moon
rise/set does not occur on every date in every location. Additionally, either the percentage illumination of the
moon is shown, or the time of the specific moon phase event (new moon, first quarter, full moon, last
quarter).
The new moon (or a waxing crescent moon) may not be visible for up to three days depending on timing and
location. The best time to try to view the new moon is shown in brackets for such days. If the new moon is
predicted to be invisible, or only to be visible with the aid of a telescope or binoculars, this is indicated by one
of two icons:
New moon is not visible
New moon only visible with an optical aid
Azimuth information is given relative to true north and is not corrected for magnetic declination.
2: Twilight times
Times of civil, nautical and astronomical twilight are shown. The different twilight times are defined as follows:
Civil: when the sun lies 0° – 6° below the horizon
Nautical: when the sun lies 6° – 12° below the horizon
Astronomical: when the sun lies 12° – 18° below the horizon
Note: not all twilight phases occur in all locations/times - for example, the sun may never set far enough for
there to be an astronomical twilight phase at northern latitudes in summer.
3: Details
The Details page shows the azimuth and altitude of the sun and moon for a specific time of day. You can use
the slider on the map to adjust the time of day. Use this to check orientation of the sun or moon relative to
features of the landscape or city at the time of your shoot.
By default, the slider covers a full 24 hour period. Touch the button to the right of the
slider to reduce the slider range to one hour for finer control of the precise time.
In addition to the normal rise/set azimuth lines, lines denoting the current azimuth of the
sun and moon are displayed. The moon line is shown only when the moon is above the horizon. The sun line
is shown during twilight times and when the sun is above the horizon.
4: Shadow length
You can determine the length of shadows for different times of day for objects of a specified height. The app
will set a default object height calculated to ensure that shadow lengths are visible based on the area covered
by the map display on first use. You can edit the object height by touching object height text field and entering
a new value.
You might, for example, set the object height equal to the known height of a building. The app will then
display the length of shadow cast by the building for the selected time of day. To view the sun or moon
directly behind the top of a building at a specific time, you would plan to position the camera at the end of
the shadow projection shown on the map.
Important: shadow lengths assume flat terrain - the actual shadow length may vary significantly from the
displayed value on sloping terrain. You can check to see if the terrain is flat using topographic maps or the
file://localhost/Users/stephen/Documents/Development/iPhone/TPE/web/iTPEHelp.html
3/9
9/17/13
TPE for iOS
geodetics function.
Shadow lengths are shown on the map using lines:
Sun shadow
Moon shadow
Note: moon shadows are only visible when the sun is set and, in most cases, only in dark areas at times when
the moon's disc is sufficiently illuminated (i.e. not at times of new moon).
5: Geodetics
The geodetics page allows you to place a secondary pin (grey) on the map. Once positioned, the
distance, bearing and change in elevation between primary and secondary sites are displayed,
together with the elevation angle. You can compare the elevation angle with the altitude of the sun or moon
to determine if the sun/moon is higher or lower than a ridge-line or hill, for example.
The slider on the map remains visible so you can adjust the time of day to match the sun or moon azimuth to
the bearing line between the pins (shown in grey). If the sun or moon is lower than the elevation angle from
primary to secondary, its azimuth is shown as a dashed line when within 10° of the bearing line, to indicate
that the sun or moon may be blocked from view.
TPE uses elevation data from the Shuttle Radar Topography Mission (SRTM30). Data points are spaced
90m (295ft) apart. If the distance between the map pins is less than the data spacing, a warning icon is
displayed indicating that there may not be sufficiently granular data available to calculate accurate results.
6: Visual search: sun
Drop the secondary pin at the desired bearing angle. Click next or previous to search. The app will find the
next date when the sun rises or sets at the bearing specified. Rise or set is determined automatically by where
you place the secondary pin (the sun rises in the east and sets in the west).
If the bearing is farther north or south than the sun rises/sets at the current location, a warning is displayed.
For locations in the far north or south, searches may take longer (as a less efficient algorithm must be used).
7: Visual search: moon
Drop the secondary pin at the desired bearing angle. Optionally click the full moon/new moon button to
switch search modes. Click next or previous to search forward or back from the current selected date.
The app will find the closest match for moon rise or moon set in the next or previous two years from the
current selected date. If a match within ±0.5° of the specified bearing cannot be found, a warning alert is
displayed. The app will check the exact date of moonrise/set ±1 day (when the moon is almost full/new).
8: Horizon
Sunrise occurs sooner when standing on top of a mountain looking east over a plain, due to the height
of the observer above the horizon. TPE can account for this effect by allowing you to specify the
elevation above sea level at the horizon.
Either touch the text field to enter a value manually (in your selected units, feet or meters) or reposition the
secondary pin (grey) and TPE will find the elevation at that point and enter it into the field for you.
The distance between the primary and secondary pins is displayed alongside the implied distance to the visible
horizon from the primary location. This value can be calculated theoretically from the difference in elevation
together with the curvature of the earth.
If you set elevation at the horizon using the secondary pin, but the distance between the pins is significantly
different from the distance to the horizon, you should adjust the secondary position to make the distances
match more closely for more accurate results.
Once set, times of sun/moon rise/set are adjusted for the height above the horizon implied by the difference
file://localhost/Users/stephen/Documents/Development/iPhone/TPE/web/iTPEHelp.html
4/9
9/17/13
TPE for iOS
in elevation from the primary pin. On the Rise/Set page (page 1) a horizon icon is shown bottom left to
indicate that times are adjusted for height above the horizon. Touch the icon to move directly to the
Horizon page.
When elevation at the horizon is set, an map overlay is displayed showing the predicted distance to the visible
horizon. Remember that the distance to the horizon will vary based on direction: the distance shown is based
on the elevation at the horizon that you have specified.
Dates
Set the selected date for the app by touching the disclosure button at the top of this screen. You can select a
date in the past or future. Touch today to return to the current date for the map primary pin position
(remember, because of time zone changes, this may be different from today in your actual physical location).
Note: remember you can adjust the selected date one day at a time by double tapping on the right or left of
the pages on Map view.
Dates of key celestial events for the selected year are shown in the table below. Adjust the displayed year
using the plus and minus buttons. Touch an event to go to the date indicated.
When the filter is set to ‘on’, the event list includes:
Full moon
New moon
Moon at perigee
Equinox
Solstice
Additional events are shown when the filter is set to ‘off’:
First quarter
Last quarter
Moon at apogee
Perigee is the moment at which the moon reaches its closest approach to earth during the monthly lunar
cycle, appearing largest in the sky. When perigee coincides with a full moon, a perigee moon (also known as a
‘supermoon’) can be observed.
Apogee is the moment at which the moon reaches its greatest distance from earth during the monthly lunar
cycle, appearing smallest in the sky.
Equinox occurs twice a year, during spring and autumn, when the sun lies directly over the equator. Sunrise
and sunset occur more or less due east at these times.
Solstice also occurs twice a year, during mid-summer and mid-winter, when the sun rises or sets at its
maximum and minimum azimuth.
Where a lunar event indicates x% larger, this represents the observed size of the moon's disc relative to its
size when the moon is at extreme apogee (farthest from Earth).
Locations
Touch the Locations tab to save your favorite places. Touch the "+" button to add a new location. If you have
not moved the primary pin since the last place name search, then the new location name defaults to the
search term you entered previously. You can edit this, keep the default, or use the suggested name that the
app displays. Touch the suggested name field next to the Use button to view alternative suggested names.
You can fine tune the location by setting the coordinates directly. The distance of the specified coordinates
from the current primary pin location is shown, along with the direction. You can go to the specified
coordinates directly to double check the location before saving. Alternatively, you can set the location
file://localhost/Users/stephen/Documents/Development/iPhone/TPE/web/iTPEHelp.html
5/9
9/17/13
TPE for iOS
coordinates to be the same as the primary pin location by touching the Use primary pin coordinates button.
TPE saves the timezone and elevation above sea level for your new location (as long as the device has internet
connectivity) so you can obtain accurate rise/set information for saved locations without the need for
network connectivity at a later time.
To go to a saved location, simply tap the desired location in the list.
Locations Export
You can export your locations from TPE as a KML file. KML ( Keyhole Markup Language ) is a text-based file
format widely used to share geographic information between applications.
To export your locations, tap the action button at the top of the Locations list. Choose "Export Locations".
Once exported, you can email the KML file to an address of your choosing.
Importing Locations
You can import locations from a KML or KMZ (zipped KML) document by sending the file as an email
attachment. Open the email on your iOS device, and then open the attachment in TPE (you may need to
choose Open In…, then TPE). TPE will prompt you to ask if you want to import locations from the file. If you
choose Import, any locations found in the document will be added to your locations list.
Note: not all KML files will contain locations that TPE can import. Specifically, TPE looks for Placemark
entries in the KML document that include latitude/longitude coordinates.
Warning: TPE does not attempt to detect duplicate locations in any KML file that is imported. If you import
the same file twice, you will end up with duplicate locations in your list.
Settings
Maps
The following map types are available:
Standard
Satellite
Hybrid
Google Standard (iOS 6+ only)
Google Satellite (iOS 6+ only)
Google Hybrid (iOS 6+ only)
Google Terrain
OpenCycleMap Topographic
MapQuest OpenStreetMap
MapQuest Open Aerial
The first three choices correspond to built-in iOS map types. Under iOS 5, these maps are provided by
Google. In iOS 6, these are provded by Apple. Under iOS 6, Google Maps are available as web-based maps
(presented in an embedded web browser). The remaining choices are presented as overlay maps (displayed
on top of the base Hybrid map type where available).
Overlay map types can be stored for use offline (when your device is not connected to the internet). The
built-in map types are only available when your device has internet connectivity (although map tiles may be
visible if they have been viewed recently, this should be relied on).
Topographic maps include topographic and cycle route information from OpenCycleMap.org . Topographic
maps are available between 60°N and 47°S. Outside these latitudes, a non-topographic map is presented. If
Topo map tiles are unavailable for the selected region or zoom level, the Hybrid map type is displayed instead.
Note: available map types are subject to availability from the map service provider. Changes in terms under
which a given map type is made available may result in the removal, substitution or addition of map types with
file://localhost/Users/stephen/Documents/Development/iPhone/TPE/web/iTPEHelp.html
6/9
9/17/13
TPE for iOS
different versions of TPE.
Note: overlay map load times may vary from those observed for other maps types, due to differences in
server infrastructure and performance. Additionally, Topographic map contour lines are annotated in meters
at all times.
Offline store allows you to specify how much device storage may be used for offline overlay map image data.
The settings page shows approximately how much storage is required (this varies based on your device screen
size and resolution).
When the offline store is enabled, all overlay map tiles are saved automatically for offline use, as long as
storage space is available.
Show current location determines whether or not the device displays your current location on the map. Set to
off to conserve battery life.
Time zone
Time zone detection is set to automatic by default (recommended). If time zone information cannot be
retrieved, you may be prompted to set a time zone manually. Switch automatic detection off (if necessary)
and touch the disclosure button next to the time zone name to select an offset from GMT.
General
Imperial/English units for height and distance can be set to Imperial (feet/miles) or Metric (meters/km).
Use magnetic north: when set to off, all numerical azimuths, headings and bearings are relative to true north.
When set to on, they are relative to local magnetic north. TPE uses the World Magnetic Model to calculate
magnetic declination for the primary pin location and selected date. Declinations are supported for dates
between 2010-2015. Outside of this date range, declination may be inaccurate.
Moon azimuth lines: set to on to show moonset, moonrise and moon position azimuth lines on the map.
Version shows the current version of TPE.
Analytics
Share usage data: this setting controls whether or not anonymous usage information is sent from TPE. This
information helps us understand how you use TPE and assists us in continuing to improve it. No personally
identifiable information is sent. If set to ‘Off’, we will only log that TPE was started, and, if the app crashes, the
crash report. No other diagnostics or usage information is collected. Please see our privacy policy for
additional detail.
Using TPE Offline
TPE can be used without a network connection, but with some limitations:
Built-in maps require a data connection
Google web maps (Terrain under iOS 5, and all Google map types under iOS 6) will not function
offline
Offline maps will display any map tiles previously stored (see below)
Automatic timezone detection is unavailable – you can specify a time zone manually (or use a saved
location)
Automatic detection of elevation above sea level for new locations is unavailable – mean sea level is
assumed
Secondary pin functionality is unavailable (as elevation is required)
Important: Google web maps require internet connectivity for map data, map markers (pin) and overlays
(azimuth lines) . Please ensure you switch to another map type when using TPE without data connectivity.
You can navigate to saved locations and the stored time zone and elevation data will be used. If you have
recently viewed the map for the location, you may find that map display is available via your device's browser
file://localhost/Users/stephen/Documents/Development/iPhone/TPE/web/iTPEHelp.html
7/9
9/17/13
TPE for iOS
cache, but this should not be relied on (except as described below).
If location services are available, you can go to your current location, but map data will normally be
unavailable. TPE will calculate all rise/set, twilight and detail azimuth/altitude information assuming the location
is at sea level. Geodetics and Horizon adjustment will be unavailable.
If TPE is unable to retrieve the correct time zone for the current primary pin position, you will be prompted
to specify a time zone manually.
Using Offline Maps
Certain map types support offline use. Currently, offline support is offered for OpenCycleMap Topographic
Maps, MapQuest OpenStreetMap and MapQuest Open Aerial map types.
To make a map available offline, ensure the Offline store is first enabled in settings. Then view the locations
you want available offline, ensuring that you zoom in and out to cover all the views you need.
TPE will store offline map tiles for up to a year, storage space permitting. If the offline map store is full, then
on start-up, TPE will delete the oldest tiles to reduce the store size.
If map tiles are stored offline, but your device has network connectivity, tiles are loaded first from store,
then TPE checks with the original map tile server to see if any updated tiles are available. If they are, the
updated information is downloaded and the older version in store is replaced.
Map tiles are stored in the application documents directory, rather than the caches directory. This means that
iOS will not delete them automatically if storage on the device runs low. This is by design, to ensure that maps
you want to be available offline are there when you need them.
DISCLAIMER: you should not rely on offline maps in TPE as your primary means of navigation.
Offline map tiles are marked not to be backed up. They are excluded from device backups to iCloud and
iTunes. If you restore your device from backup, tiles that were previously available offline will not be
restored.
In summary, for offline maps, as long as there is space in your offline store, if you have viewed a map tile on
the device within the past 12 months, it will be available offline automatically.
Support
Go to photoephemeris.com/support or contact [email protected] .
Credits
Topographic maps by OpenCycleMap.org
MaqQuest tiles courtesy of MapQuest
MapQuest Open Aerial maps: portions Courtesy NASA/JPL-Caltech and U.S. Depart. of Agriculture, Farm
Service Agency
MapQuest OpenStreetMap maps: © OpenStreetMap contributors, CC-BY-SA
Selected tab bar icons by Joseph Wain / glyphish.com
Time zone and elevation data courtesy of GeoNames.org
Roger Sinnott and Stephen R. Schmitt for the moonrise, moonset algorithms
All other astronomical algorithms taken from Astronomical Algorithms, 2nd Ed. by Jean Meeus
Geodetic calculations based on T. Vincenty's work , adapted from implementations by Mike Gavaghan and the
US National Geodetic Survey
Distance to horizon calculation based on formula with refraction given by Andrew T. Young
Adjustment for height above the horizon taken from the
Explanatory supplement to the Astronomical Almanac by P. Kenneth Seidelmann
Crescent moon visibility calculations based on
"A Method for Predicting the First Sighting of the New Crescent Moon" by B.D. Yallop of HM Nautical
file://localhost/Users/stephen/Documents/Development/iPhone/TPE/web/iTPEHelp.html
8/9
9/17/13
TPE for iOS
Almanac Office
Magnetic declination derived from the World Magnetic Model (WMM2010)
Many thanks to Jeff Conrad for his expert comments and advice
"Wacht auf, es nahet gen den Tag;
ich hör' singen im grünen Hag
ein wonnigliche Nachtigall,
ihr' Stimm' durchdringet Berg und Tal:
die Nacht neigt sich zum Occident,
der Tag geht auf von Orient,
die rotbrünstige Morgenröt'
her durch die trüben Wolken geht."
© Crookneck Consulting LLC, 2010 – 2013
All rights reserved
file://localhost/Users/stephen/Documents/Development/iPhone/TPE/web/iTPEHelp.html
9/9