Visual Search is a tool in TPE Web that helps you determine when the Sun, Moon, Galactic Center, planets, or other celestial targets will appear in a specific place in the sky.
Why might you want to do this? Here’s one reason:
Moonwalk from Reel Water Productions on Vimeo.
This spectacular sequence was planned with the help of TPE.
The key to getting these sorts of shots is identifying the windows of opportunity that put the Sun, Moon, or another celestial target into the frame from your shooting location. Often you have some latitude in where you can shoot from, but sometimes you don’t – particularly when a celestial body needs to align with a specific feature in the landscape or skyline.
Visual Search is especially useful when you already have a potential shooting location or composition in mind and want to find the dates and times when the geometry will work.
Starting out with Visual Search
Visual Search is available from the 3D page in TPE Web. You can use it in either Orbit or first-person view (FPV) mode.
In Orbit mode, you can define a search using the controls in the Visual Search panel. In FPV, you can also define the search visually by drawing a Range or setting a Target directly in the scene.
- 3D Mode – Opens TPE Web’s 3D page
- Orbit Mode – The camera orbits around the primary pin and its surroundings
- First-person view (FPV) – Shows the scene from the primary pin and allows you to define Visual Search areas directly in the view
- Visual Search – Opens the Visual Search tool
- Visual Search panel – Choose the search body, duration, search mode, and other search criteria
Visual Search for the Sun is available on the Free plan. Additional celestial targets and FPV require a PRO or MAX subscription. The 3D building data used in some of the examples below also varies by subscription level.
Before running a search, choose the body or target you want to find and the duration of the search.
Visual Search searches forward from the currently selected date. This is important if you have already been browsing search results: selecting a result changes the date in TPE Web, so a subsequent search will begin from that date unless you change it again. You can return to today before searching, or use the shortcut shown beside the Search button to search from today.
Visual Search uses altitude and azimuth plus a tolerance to describe where a celestial body should appear in the sky. You can enter these values directly or – in FPV – define them visually.
There are two main search modes:
- Range searches for periods when the body passes through an area of the sky.
- Target searches for moments when the body reaches a preferred position, within the tolerance you specify.
Range is a useful place to begin because it generally returns the broadest set of possibilities. Target is useful when you have a particular alignment in mind and is usually the more appropriate mode for shots that require a tight tolerance, such as the Moon directly aligned with a building.
Visualizing a celestial body’s range across the sky
When Visual Search is enabled, TPE automatically displays the declination range limits for the selected celestial body, showing the range of positions it can occupy in the sky over time. These limits can help you see whether a planned alignment with the Sun, Moon, a planet, or another celestial target is possible before you run a search.
The limits appear as translucent bands bounded by dashed lines in the selected body’s color.
For the Sun, the range is bounded by its paths at the summer and winter solstices – the full range of positions it reaches over the course of a year.
For the Moon, TPE Web shows two ranges. The inner limits show the Moon’s range of motion over the selected search duration. A fainter outer range shows positions that may become possible over the Moon’s full 18.6 year cycle which encompases the Major Lunar Standstill when the Moon reaches its extremes of declination.
Planets can also show shorter- and longer-term limits. The longer-term planetary range is based on a 20-year period, which is currently the longest duration available for a single Visual Search.
- Moon path on the selected date – Shows the Moon’s path across the sky for the currently selected date.
- Range limit over the search period – Shows the limit of the Moon’s possible paths during the selected Visual Search duration.
- Longer-term range limit – Shows the extreme range of positions the Moon can reach over its 18.6 year cycle.
If the Range or Target you have in mind lies outside the shorter-term limits but inside the longer-term limits, extending the search duration may reveal additional opportunities. If it lies outside the longer-term limits, the search will never produce any results for that body from the selected location.
Using Range mode
Range mode searches for periods when the selected body passes through an area of the sky. This is a useful way to begin when you know roughly where you want the Sun, Moon, or another target to appear, but you have some flexibility within the composition.
In TPE Web, you can define a Range in several ways. In FPV, the quickest method is usually to draw the search area directly in the scene. Select the Range drawing tool, then drag over the part of the sky where you want the body to appear.
- Draw Range tool – Drag in FPV to define the area of sky you want to search
- Search Range – The selected area where TPE Web will look for the chosen celestial body
As you draw, TPE Web updates the minimum and maximum altitude and azimuth values in the Visual Search panel. You can also enter those values manually if you already know the range you want to search.
For our example, we’ll draw a range over the sky beside Santa Maria della Salute in Venice – an area where the Moon could work well in the composition.
Before searching, confirm the selected date and choose how long you want TPE Web to search.
Click Search to find the dates and times when the Moon passes through the selected area.
Understanding Range results
A range result represents a period of time during which the selected body passes through the search area, rather than a single instant. Each result includes information that helps you evaluate the opportunity:
- a sparkline chart showing how the body crosses the search area;
- the date;
- the start and end times;
- the approximate duration of the passage;
- additional information relevant to the selected body, such as Moon illumination.
The start and end times mark when the body enters and exits the Range.
You can click on any result to set the date and time. There are three options:
- Click the start time for when the Sun enters the search area
- Click the end time for when the Sun exits the search area
- Click anywhere else on the result to set the time to midway between start and end times (but see below for some exceptions to this rule)
Because each Range result is a window of time rather than a single instant, you can move forward or backward within that interval to your preferred position. This means Range mode can still be useful for precise compositions.
The sparkline chart provides a quick visual summary of how the body passes through the Range. One result may only clip the edge of the Range, while another may pass more centrally through it. You can use these sparklines to quickly compare the results and choose the opportunities that look most promising.
For example, the Moon might spend 45 minutes passing through the area you selected beside Santa Maria della Salute. You may decide that the best composition occurs only a few minutes after it enters the Range, or just before it leaves.
TPE Web provides both Grouped and List views for browsing results. Grouped view collects nearby opportunities together, while List view shows the individual Range results in more detail.
If your initial search returns too many results, you can either narrow the Range or use filters to identify the opportunities that also meet your other photographic requirements.
Filtering Visual Search Results
Typically you need other conditions in place as well to make a shot of the Moon or Galactic Center. For example, you may want a full Moon, or you may want to shoot the Milky Way on a moonless night. Filters let you narrow the search results to the dates that also meet those photographic conditions.
TPE Web includes a number of suggested filters for common photographic situations. For the Moon, these include:
- Supermoon – a perigee full Moon
- Full Moon – 95–100% illuminated
- New Moon – 1–5% illuminated and waxing
- Crescent Moon – 1–25% illuminated
- Near sunrise/sunset – Sun between +2° and -2° altitude
- Civil/Nautical twilight
Suggested filters for the Galactic Center include:
- Astronomical twilight – sky is almost dark and stars are visible
- Darkness – after/before astronomical twilight
- Moonless night – darkness, plus the Moon below -6°
- Crescent Moon – 1–25% illuminated, providing some moonlight for the landscape without overly impairing the stars
You can also create your own filters. Click +, choose the body, then select the parameter you want to filter by and enter the desired value or range. The available parameters depend on the selected body. For the Moon, for example, you can filter by altitude, azimuth, illuminated fraction, whether it is waxing, or its semidiameter.
- Filter Visual Search results
- Add filter
For our Venice example, we might want the Moon to appear beside Santa Maria della Salute while it is nearly full. Rather than inspecting every search result, we can add a Moon illumination filter or choose one of the suggested Moon-phase filters to narrow the results.
Filters are applied in addition to the Visual Search geometry. In other words, the Sun, Moon, or other target still has to pass through the Range you defined, but the result must also meet the additional conditions you specify. You can add more than one filter when needed. This makes it possible to look for combinations such as a particular Moon phase and a specific lighting condition.
Manually creating filter conditions allows even more flexibility, but the suggestions should cover most planning situations.
How filters apply to Range results
Because a Range result covers a period of time, a filter condition may be true for only part of that interval. TPE Web applies filters optimistically: the result is retained if the condition is met at either the start or end of the Range, and removed only if it is not met at either end.
For example, when searching for the Galactic Center on a moonless night, the Moon may rise above its max altitude threshold of -6° during the duration of the result, but if it is below the threshold at the start of the time period, the result is retained – after all, your filter conditions were met, just not for the entire duration.
(Why can’t we limit the range to the time when the filter conditions are met? That would be possible, but it would require additional interpolation or brute-force calculations on multiple variables – we’ll leave that as something for the future…)
This consideration does not arise in Target mode, as each result reflects a moment in time for which the filters can be evaluated just once.
Choosing search duration
The appropriate search duration depends on the body. For the Sun or Galactic Center, a 1-year search will usually be enough because their apparent paths vary only slightly from year to year.
The same does not apply to the Moon or planets. If your search involves one of these bodies – or if you plan to apply filters that include the Moon – you may need a longer search. Visual Search currently supports search periods of up to 20 years.
The Moon follows roughly a 19.5-year cycle, so its position varies year by year. You can’t simply look out 12 months ahead and expect to cover all the opportunities where the Moon may show up in your search range or target. The declination range limits in the 3D view can help show whether extending the search duration may reveal additional opportunities.
Using Target mode
Target mode is useful when you have a particular alignment in mind rather than a broader area of sky where the body could appear.
In FPV, select the Set Visual Search Target tool, then click the point in the scene where you want the selected body to appear. TPE Web places a target at that position and updates the corresponding altitude and azimuth values in the Visual Search panel.
Unlike Range mode, where any position within the selected area can qualify, Target mode starts with a preferred position. You can then specify how closely a result needs to match that position using the Tolerance control.
For our Target examples, we’ll continue at our spot in Venice with a view of Santa Maria della Salute, searching for when the Moon will align with the top of the dome. This gives us a specific architectural feature against which to plan a more precise Moon alignment.
You can place the Target directly on the point where you want the center of the body to appear, or use an offset to position the body above, below, or beside that point. We’ll look at offsets in more detail below.
Setting the tolerance
The Tolerance control determines how closely a result must match the Target you selected.
With a wider tolerance, TPE can return results that fall farther from the exact Target position. A tighter tolerance limits results to alignments that are closer to the Target.
Changing the tolerance also changes the size of the target area, giving you a visual indication of how much variation you are allowing.
A narrow tolerance is useful when the composition depends on a very precise relationship between the body and your subject. A wider tolerance can be helpful when you have more flexibility and want to see a larger set of possible opportunities.
Choosing altitude or azimuth priority
By default, Target mode uses Altitude priority, which you can toggle off using the control in the Visual Search panel.
With Altitude priority:
- the requested altitude is matched exactly;
- the azimuth may vary within the selected tolerance.
With Altitude priority turned off:
- the requested azimuth is matched exactly;
- the altitude may vary within the selected tolerance.
Which option is most useful can depend on the composition you are planning. For example, if keeping the Moon at an exact height above a building is most important, Altitude priority may suit the shot. If keeping it horizontally centered over a subject matters more, turning Altitude priority off may be preferable even if the Moon appears slightly higher or lower.
Why is Altitude priority recommended?
Altitude priority performs better in general than azimuth priority. TPE Web uses a variety of interpolation algorithms under the hood to obtain results efficiently, rather than calculating the position of the Sun and Moon for every minute of the day across months or years.
In the Arctic and Antarctic circles and in the Tropics, azimuth can vary over time in ways that make it unsuitable for standard interpolation techniques (think higher-order polynomials – or rather, don’t; it’s just a headache!). As a result, for some locations and dates, the interpolation may fail to produce acceptable results. This is particularly the case when searching azimuths near to the meridian – when azimuth equals 0° or 180°.
For this reason, we recommend using Altitude priority or enabling Range mode.
Turning Altitude priority off can still be useful when the body moves predictably across the sky with only a slow change in azimuth. This is often the case for the Galactic Center, where azimuth-based targeting can work well.
Understanding Target results
Target results differ from Range results in an important way. A Range result describes a window of time while the body passes through an area. A Target result identifies a particular moment when the body reaches – or comes acceptably close to – the position you specified.
Each result includes a small target graphic showing where the alignment falls relative to the Target you specified. Results do not have to fall exactly on the center of the Target to qualify – they can also be returned when they fall within the tolerance you selected.
With Altitude priority turned on, all of the results match the requested altitude. The variation shown in the target graphic is therefore in azimuth – how far left or right the result falls from the exact Target. If you turn Altitude priority off, the opposite applies – azimuth is matched exactly, while altitude may vary within the tolerance.
This distinction is important when evaluating the results. A result does not necessarily mean that the body will be centered exactly on the Target from the original camera position. It may instead mean that the alignment falls within your allowed tolerance.
The position of the green dot in the result graphic gives you a quick visual indication of how the result differs from the exact Target. This makes it easier to compare several results and decide which alignments best suit your composition.
Offsetting the Target
By default, Target mode searches for times when the center of the selected body aligns with the point you clicked. You can use an offset when you want the body to appear above, below, or beside that point instead.
For example, in our Venice composition, we might use the top of the dome of Santa Maria della Salute as the Target but position the Moon slightly above or to one side rather than centering it directly on the dome.
TPE Web provides two ways to set the offset:
- Square mode provides a broader, freeform area for positioning the body relative to the Target.
- Circle mode provides finer control using the apparent size of the selected body. For the Moon, the circle extends to approximately four semidiameters from the Target – about two Moon diameters.
In Circle mode, you can place the offset freely or hold Shift while clicking to snap the position to the nearest clock-face direction and semidiameter increment. For example, placing the Moon at 3:00 positions it directly to the right of the Target.
You can also enter the offset values directly in the Visual Search panel.
Allowing for camera movement
If you have some flexibility in where you can stand, Target mode can include nearby shooting positions as part of the search.
Enter the distance you are able to move in the Camera movement across ± field. TPE Web can then search for alignments that become exact by shifting the shooting position within that distance, which can return more opportunities than searching from a completely fixed position.
With Altitude priority turned on, the movement is lateral – left or right – because TPE Web is adjusting the azimuth while preserving the requested altitude. With Altitude priority turned off, the movement is forward or backward so that TPE Web can adjust altitude while preserving the requested azimuth.
Only enter movement that is realistic at the location. A beach or open overlook may allow considerable freedom, while a bridge, shoreline, road, wall, or other obstacle may limit where you can actually stand.
Camera movement is intended for modest adjustments around a planned shooting position rather than for searching a large surrounding area. We suggest approximately 30 ft (10 m) in either direction as useful guidance. For broader searches for possible shooting positions, use Shot Alignment instead.
Using your own height data
In most cases, if the building or object you want to align with is already represented accurately in TPE Web’s 3D view, you can set the Target directly in FPV without entering a separate height.
There are times, however, when you may want to supply your own height information:
- If the building or object is not represented in TPE Web’s 3D data, you can use Geodetics and enter the object’s height manually.
- If you have your own height data and prefer to use it instead of TPE Web’s building data, you can enter that value as the Target height.
Choosing between building data and Photorealistic 3D
The 3D representation you use can affect how precisely you are able to place a Range or Target against buildings and other features.
TPE Web’s standard 3D view combines terrain data with separately modeled buildings. Where detailed building data is available, this can provide a useful representation for planning alignments. Building coverage and detail vary by location and subscription level.
Google Photorealistic 3D takes a different approach. Rather than placing separate building models on top of terrain, it uses a single 3D surface mesh that can include terrain, buildings, vegetation, bridges, and other features. This can provide a much more detailed visual representation.
The difference matters when you are working from an elevated position. In our Venice example, the primary pin is positioned on the Accademia Bridge rather than at ground level. With ordinary terrain and building data, you may need to account explicitly for the camera’s height above ground; here, the Red Pin is offset by 21 ft to account for the bridge. In Photorealistic 3D, however, the surface mesh may already place you on the elevated structure.
Be careful not to account for the same height twice. If the Photorealistic 3D surface already represents the bridge, platform, roof, or other elevated feature you are standing on, adding the full height again can place the camera too high.
Photorealistic 3D and the standard terrain/building view also have different strengths. Photorealistic 3D can provide detailed representations of structures, vegetation, and other obstructions, while the standard terrain view provides dynamic lighting that is useful for understanding how sunlight and shadow fall across the landscape. They are complementary rather than interchangeable.
See: 3D Buildings in TPE – What’s Available on the Maps and 3D Pages
Saving a Visual Search or Shot Plan
Once you have created a useful Visual Search, you can save it to the Library so you can return to the same search criteria later.
A saved Visual Search stores the search setup, rather than a particular result date. When you reopen it, the search runs forward from the date you start from at that time.
If you find a particular result that you want to return to – for example, a specific Moon alignment on a particular date and time – save that opportunity as a Shot Plan instead.
This gives you two different ways to preserve your planning:
- save the Visual Search when you want to reuse the search criteria;
- save a Shot Plan when you want to preserve a specific photographic opportunity.
Two crossing results near the meridian
If you’ve made it this far, you might be interested to learn about the exceptions to Range mode results that were mentioned earlier. These can arise if the azimuth range you specify spans the meridian. In these cases, it is possible for the body (Sun/Moon/Galactic Center) to rise through the target range and then set back through it once again. Here’s an example for Iceland in 2022 as we approach the major lunar standstill:
With a wide enough azimuth range, you may see ‘compound’ results with two crossings through the target range.
In these circumstances, clicking the result once will set the time to the midpoint of the first crossing. Clicking it again will set it to the middle of the second crossing.
In some circumstances, the interpolation algorithm may return incomplete results, and clicking the result listing may select only one of the two crossings.
Visual Search and Shot Alignment
Visual Search is especially useful when you already have a potential shooting location or composition and want to find the dates and times when the desired alignment occurs.
If your main question is instead where you could stand to obtain an alignment over a broader area, Shot Alignment is usually the better tool.
There is some overlap between the two. Target mode can account for modest camera movement around your selected position, but it is not intended to search a large surrounding area for possible shooting locations. Shot Alignment is designed for that broader spatial search.
