Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# OrthoStreamXP

![OrthoStreamXP: free, open-source photo scenery for X-Plane 12, streamed as you fly](docs/images/banner.jpg)

**Fly over real-world aerial imagery in X-Plane 12 — without downloading entire regions in advance.**

OrthoStreamXP streams photo scenery as you fly, loading the areas around your aircraft first and keeping downloaded imagery ready for your next flight.
Expand Down Expand Up @@ -79,12 +81,13 @@ The installer is not currently code-signed, so Windows may display a warning tha

## Choose your scenery quality

OrthoStreamXP provides four presets:
OrthoStreamXP provides five presets:

- **Balanced** — prioritises a balance between visual detail and resource use.
- **Sharp** — the recommended starting point for most systems.
- **Ultra** — for systems with more graphics memory available.
- **Extra** — the highest preset, intended for systems with greater resources.
- **Dynamic** — Extra near the ground, Sharp from 5,000 ft and Balanced from 25,000 ft above it. High up, X-Plane still asks for full detail it cannot show, so Dynamic saves about half the downloads in a climb and cruise. On a descent it returns to full detail early, before the ground comes close.

You can change presets in Settings. OrthoStreamXP also reports graphics memory usage from your flights and warns when the measured scenery requirements exceed your card's available memory.

Expand Down
Binary file modified docs/OrthoStreamXP-UserGuide.pdf
Binary file not shown.
2 changes: 1 addition & 1 deletion docs/first-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ This is where OrthoStreamXP keeps the pictures it downloads and the textures it

![Setup step 5: Quality](images/setup-quality.png)

Pick how sharp the ground should be: **Balanced**, **Sharp**, **Ultra** or **Extra**. Each card shows the texture size, the imagery zoom level, the metres per pixel, and roughly how long a new area takes to load. See [Settings › Quality](settings.md#quality) for a comparison.
Pick how sharp the ground should be: **Balanced**, **Sharp**, **Ultra**, **Extra** or **Dynamic** (Extra near the ground, less detail high up, where it cannot be seen). Each card shows the texture size, the imagery zoom level, the metres per pixel, and roughly how long a new area takes to load. See [Settings › Quality](settings.md#quality) for a comparison.

**Not sure?** Click **Test my connection** (it says **Test again** if you have tested before). OrthoStreamXP downloads real pictures for about 30 seconds, then:

Expand Down
5 changes: 4 additions & 1 deletion docs/flying.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ The Home page has two ways to start:

Turn on **Start when OrthoStreamXP opens** if you want the scenery to start every time you open the app.

When **Start and fly** starts X-Plane, OrthoStreamXP waits until X-Plane's window is in front, then moves out of its way to the notification area next to the clock. Click its icon to open the window again, or right-click it for **Open OrthoStreamXP** and **Exit**. When X-Plane quits, the window comes back on the Home page, ready to stop the scenery and show your flight report. If you start X-Plane yourself, the window stays where it is.

If X-Plane was already running when you started OrthoStreamXP, Home shows **Restart X-Plane**. Quit X-Plane and start it again to see the photos.

## The Home page
Expand All @@ -25,7 +27,8 @@ Before your first start, Home shows **How it works**: start OrthoStreamXP, start

From top to bottom:

- **Status card.** Shows whether OrthoStreamXP is stopped, starting, ready (*Photo scenery is ready*) or in use (*Flying with photo scenery*). The **Start** button becomes **Stop** while it runs. The dot at the bottom of the sidebar shows the same state on every page.
- **Check for updates.** Looks for a new version straight away (see [Troubleshooting › Updates](troubleshooting.md#updates)).
- **Status card.** Shows whether OrthoStreamXP is stopped, starting, ready (*Photo scenery is ready*) or in use (*Flying with photo scenery*). The **Start** button becomes **Stop** while it runs. The dot at the bottom of the sidebar shows the same state on every page. Above it, the theme button switches the window between the Windows theme, light and dark.
- **Notices.** Tuning suggestions, updates and problems appear here, each with a button for the next step.
- **Last flight.** A report on your most recent flight, shown while OrthoStreamXP is stopped (see below).
- **Session figures** (*This session* while it runs, *Last session* after it stops): how many textures X-Plane got, how many of its reads got the real picture, how many textures are being built now, and the download speed or the number of picture tiles downloaded.
Expand Down
Binary file modified docs/images/about.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/banner.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/cache-quality.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/cache.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/home.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/packages.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/settings-colours.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/settings-download.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/settings-folders.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/settings-night.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/settings-other.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/settings-quality.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/settings-tuning.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/setup-cache.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/setup-quality.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/setup-ready.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/setup-scenery.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/setup-welcome.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/setup-xplane.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 16 additions & 0 deletions docs/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,24 @@ Choose how sharp the ground is. Each preset comes with settings tested for it an
| **Sharp** | 2048 px | 16, 17 near airports | ~3.4 m per pixel | Everyday flying, approaches included |
| **Ultra** | 4096 px | 17, 18 near airports | ~1.7 m per pixel | Low flight and GA, with plenty of graphics memory |
| **Extra** | 4096 px | 17, 19 near airports | ~1.7 m per pixel | Low and slow flight and screenshots, on a fast connection |
| **Dynamic** | Extra's near the ground, less higher up | as Extra below 5,000 ft | follows the height | Climbs, cruise and approaches in one flight, on a fast connection |

**Extra** is Ultra with the finest imagery (zoom 19) near airports, which often avoids clouds and other artefacts. Elsewhere it is the same as Ultra. Near airports it downloads four times as much as Ultra, and a new area takes a little longer to load: about 4 minutes, then sharp next to the aircraft.

### Dynamic

**Dynamic** makes the detail follow your height above the ground:

- **Below 5,000 ft** it is Extra.
- **From 5,000 ft** the photos are downloaded at Sharp's detail.
- **From 25,000 ft** they are downloaded at Balanced's detail.

High up, X-Plane still asks for the photos in full detail, though from there the detail cannot be seen. Dynamic downloads about half as much in a climb and cruise, which suits airliners and other high flying.

On a descent, Dynamic looks four minutes ahead and goes back to full detail early, so the ground is sharp again before you come close to it. X-Plane does not load a photo again just because you came lower: one it loaded with less detail high up stays that way while X-Plane keeps it. That is why the switch back comes early.

Dynamic shares Extra's textures in the cache, so you can switch between the two without downloading anything again, and photos already in the cache are shown as they are at any height. It needs X-Plane to send the aircraft's position, which it does on the same PC by itself. The heights can be changed in the settings file (**Show the file**): `dynamic-sharp-above` and `dynamic-balanced-above`, in feet.

Each card shows the imagery zoom, the metres per pixel, roughly how long a new area takes to load, and how much graphics memory the photo textures take. Until you have flown, that memory figure comes from a test flight; after your first long flight, it is measured on your PC.

- The **Recommended** badge marks the preset that suits your connection and graphics card, with the reason below it.
Expand Down Expand Up @@ -57,6 +72,7 @@ Your scenery packages are not changed: OrthoStreamXP adjusts the terrain files a

- **Where the pictures come from:** the imagery source.
- *Bing, then Esri where Bing has no picture* (recommended): the sharpest pictures in most places.
- *Esri (ArcGIS), then Bing where Esri has no picture*: in some regions Esri's photos are newer or clearer than Bing's.
- *Bing only*.
- *Geoportal in Poland (national orthophoto), Bing and Esri elsewhere*.
- **Downloads at once:** how many pictures download in parallel, from 16 to 256. Your internet connection sets the real speed; beyond about 160, more downloads only wait longer. Lower this if other programs need the connection while you fly.
Expand Down
2 changes: 1 addition & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ The About page shows your version, whether WinFsp is installed (with a **Get Win

## Updates

OrthoStreamXP checks for updates when it opens and from time to time while it runs, and downloads a new version in the background. When the update is ready, Home shows **OrthoStreamXP x.y.z is ready to install**. If the scenery is streaming, finish your flight and stop it first; then click **Update and restart**. Your settings, cache and flight history stay.
OrthoStreamXP checks for updates when it opens and from time to time while it runs, and downloads a new version in the background. To look straight away, click **Check for updates** at the top of the Home page; if there is nothing new, OrthoStreamXP tells you that you already have the newest version, or why it could not look. When the update is ready, Home shows **OrthoStreamXP x.y.z is ready to install** at the top of the page, above the status card. If the scenery is streaming, finish your flight and stop it first; then click **Update and restart**. Your settings, cache and flight history stay.

## Uninstalling

Expand Down
18 changes: 18 additions & 0 deletions release-notes/v1.4.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
## What's new

- **Dynamic quality.** A new preset in **Settings** (and in the setup): **Dynamic**. Near the ground it is the same as Extra. From 5,000 ft above the ground it downloads the photos at Sharp's detail, and from 25,000 ft at Balanced's. High up, X-Plane still asks for full-detail photos even though you cannot see that detail from there, so Dynamic downloads about half as much in the climb and the cruise. When you descend, it goes back to full detail early, so the ground is sharp again before you get close to it.

## Why it matters on a jet flight

Picture a short airliner hop. You take off, and in about twenty minutes you are at 35,000 ft. You stay up there for most of the flight, with the ground almost seven miles below you, and the descent and approach take the last half hour or so. In a jet, most of the flight is spent high above the ground.

Up there you see whole valleys and coastlines, but not single houses or field edges. X-Plane still asks for the photos at the same full detail it would want at 1,000 ft. Until now OrthoStreamXP did exactly that, so most of what it downloaded in the cruise was detail no one could see. It used your connection and processor and filled the cache, and it could hold up the photos you actually look at.

With Dynamic, the photos follow your height. In the climb and cruise they come at Sharp's and then Balanced's detail, which still looks good from that high, and the downloads drop by about half. Once you start down, Dynamic looks a few minutes ahead and goes back to full detail early, so the approach, the runway and the area around the airport are as sharp as with Extra. You get the same view from your seat, with much less downloading in the middle of the flight.

## Good to know

- Your preset is not changed by the update. To try Dynamic, choose it in **Settings** while OrthoStreamXP is stopped. It applies from the next start.
- Dynamic uses the same cache as Extra, so photos you already downloaded with Extra are still used, and switching between the two downloads nothing again.
- Photos that are already in the cache are shown as they are, at any height. Dynamic only changes what is downloaded new.
- A photo X-Plane loaded at lower detail high up stays that way until X-Plane loads it again. This is why Dynamic goes back to full detail well before the ground comes close on a descent.
19 changes: 19 additions & 0 deletions src/OrthoStreamXP/Configuration/MountSettings.cs
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ internal sealed record MountSettings
public bool SkipPhotosAtNight { get; init; }
/// <summary>How far below the horizon, in degrees, the sun must be before the photos are skipped (0-18).</summary>
public double SkipPhotosSunBelow { get; init; } = -Scenery.Daylight.DefaultDarkBelow;
/// <summary>Dynamic quality: the photos' detail follows the height above the ground; null when it is off.</summary>
public Scenery.DynamicOptions? Dynamic { get; init; }
/// <summary>A texture-quality value from an older settings file: no longer used, noted in the log.</summary>
public string? IgnoredTextureQuality { get; init; }
/// <summary>Photo textures are served level by level as X-Plane reads them (off: built whole first).</summary>
Expand Down Expand Up @@ -153,6 +155,7 @@ public static MountSettings FromValues(SettingValues values, bool console = true
bool skipPhotosAtNight = ParseOnOff(skipValue) ?? throw new SettingsException($"skip-photos-at-night must be on or off, not '{skipValue}'");
double skipSunBelow = values.Double("skip-photos-sun-below", -Scenery.Daylight.DefaultDarkBelow);
if (skipSunBelow is < 0 or > 18) throw new SettingsException("skip-photos-sun-below must be between 0 and 18 degrees");
Scenery.DynamicOptions? dynamic = ParseDynamic(values);

if (downloadWorkers < 1) throw new SettingsException("download-workers must be at least 1");
if (downloadTimeout is < 1 or > 120) throw new SettingsException("download-timeout must be between 1 and 120 seconds");
Expand Down Expand Up @@ -208,6 +211,7 @@ public static MountSettings FromValues(SettingValues values, bool console = true
NightLights = nightLights,
SkipPhotosAtNight = skipPhotosAtNight,
SkipPhotosSunBelow = skipSunBelow,
Dynamic = dynamic,
IgnoredTextureQuality = values.String("texture-quality"),
MipStreaming = mipStreaming,
NearWait = nearWait,
Expand Down Expand Up @@ -309,6 +313,21 @@ internal static SeasonOptions ParseSeasons(SettingValues values)
return new SeasonOptions(on, strength / 100, choice);
}

/// <summary>Dynamic quality's steps, or null when it is off.</summary>
private static Scenery.DynamicOptions? ParseDynamic(SettingValues values)
{
string onValue = values.String("dynamic-quality") ?? "off";
bool on = ParseOnOff(onValue) ?? throw new SettingsException($"dynamic-quality must be on or off, not '{onValue}'");
double sharp = values.Double("dynamic-sharp-above", Scenery.DynamicOptions.DefaultSharpAboveFt);
if (sharp is < 1000 or > 40_000) throw new SettingsException("dynamic-sharp-above must be between 1000 and 40000 feet");
double? balanced = values.String("dynamic-balanced-above") is { } text && ParseOnOff(text) == false
? null
: values.Double("dynamic-balanced-above", Scenery.DynamicOptions.DefaultBalancedAboveFt);
if (balanced is < 1000 or > 60_000) throw new SettingsException("dynamic-balanced-above must be between 1000 and 60000 feet, or off");
if (balanced <= sharp) throw new SettingsException("dynamic-balanced-above must be higher than dynamic-sharp-above (or off)");
return on ? new Scenery.DynamicOptions(sharp, balanced) : null;
}

internal static bool? ParseOnOff(string value) => value.ToLowerInvariant() switch
{
"on" or "true" or "yes" => true,
Expand Down
7 changes: 5 additions & 2 deletions src/OrthoStreamXP/Configuration/SettingsOptions.cs
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,10 @@ internal static class SettingsOptions
.Add("night-lights", "on or off: light the towns on the photo scenery at night. X-Plane's own scenery glows where it is a town; photo tiles are dark but for X-Plane's roads and buildings. With this on, each photo tile gets a night texture of street lamps, their glow and lit windows along X-Plane's roads (read from the overlay packages), which X-Plane fades in at dusk. Each is painted the first time X-Plane loads it and kept in the cache. The packages' files are not changed. Takes effect at the next start (default: off)")
.Add("skip-photos-at-night", "on or off: at night in X-Plane (the sun lower than skip-photos-sun-below) download no detailed photos: the ground under the night lights is drawn from the low-zoom base, blurry, and what is already in the cache is shown as it is. In twilight, and before X-Plane sends where the sun is, the photos stream as usual. Saves downloads and processor time on night flights; needs mip-streaming. Takes effect at the next start (default: off)")
.Add("skip-photos-sun-below", "Degrees, 0-18: how far below the horizon the sun in X-Plane must be before skip-photos-at-night skips the photos. 6 is the end of civil twilight, when the sky turns dark; 12 the end of nautical twilight, when the horizon fades; 18 full night. Lower skips more of the twilight; higher keeps the photos while the sky still lights the ground, and brings them back sooner at dawn. Takes effect at the next start (default: 9)")
.Add("lazy-terrain-listing", "Show an empty terrain directory listing; DSF-referenced .ter files remain directly accessible", arity: 0)
.Add("dynamic-quality", "on or off: Dynamic quality, the photos' detail follows the height above the ground. X-Plane wants nearly the same full-detail textures at 10,000 ft as at 1,000 ft, though from up there the detail cannot be seen; with this on, above dynamic-sharp-above the photos are fetched no sharper than Sharp's (2048 px), and above dynamic-balanced-above no sharper than Balanced's (1024 px). What is already in the cache is shown as it is. In a descent the height four minutes ahead counts, so the photos are sharp again before the ground comes close. Saves about half of the downloads in a climb and cruise; needs mip-streaming and track-aircraft. The Dynamic preset sets it with Extra's values. Takes effect at the next start (default: off)")
.Add("dynamic-sharp-above", $"Feet above the ground, 1000-40000: from this height Dynamic quality fetches the photos no sharper than Sharp's; they are sharp again 500 ft below it (default: {Scenery.DynamicOptions.DefaultSharpAboveFt:0})")
.Add("dynamic-balanced-above", $"Feet above the ground, 1000-60000, or off: from this height Dynamic quality fetches the photos no sharper than Balanced's; it must be higher than dynamic-sharp-above (default: {Scenery.DynamicOptions.DefaultBalancedAboveFt:0})")
.Add("lazy-terrain-listing","Show an empty terrain directory listing; DSF-referenced .ter files remain directly accessible", arity: 0)
.Add("prefetch-loaded-scenery", "on or off: build the textures of each DSF X-Plane loads as soon as it opens the DSF's terrain definitions, before X-Plane asks for them one by one (default: on)")
.Add("track-aircraft", "Follow the aircraft through X-Plane's UDP DATA output (row 20) and build the loaded scenery's textures ahead of it", arity: 0)
.Add("xplane-address", "Where X-Plane listens for UDP requests; the aircraft position is requested from it, so nothing has to be set up in X-Plane (default: 127.0.0.1:49000)")
Expand All @@ -59,5 +62,5 @@ internal static class SettingsOptions
.Add("season", "auto (X-Plane's date and the place), or a season for everywhere: early-spring, spring, summer, early-autumn, autumn, late-autumn, winter (default: auto)")
.Add("exposure", $"How much light the photo textures let through, {Exposure.Min}-{Exposure.Full} percent: less darkens them evenly, as a camera's exposure, where they look brighter than X-Plane's own scenery. The cache keeps the imagery as downloaded (default: {Exposure.Full})")
.Add("season-land-cover", "No longer used: the seasons go by the colours alone (accepted so older settings files still load)")
.Add("read-log", @"on or off: log every open and read X-Plane makes through the mount, and the camera position, as CSV files in the logs folder (reads-*.csv, camera-*.csv), for finding a problem; the flight tuning measures the paging model without them (default: off)");
.Add("read-log", @"on or off: log every open and read X-Plane makes through the mount, the camera position and every streamed build with what it downloaded, as CSV files in the logs folder (reads-*.csv, camera-*.csv, builds-*.csv), for finding a problem; the flight tuning measures the paging model without them (default: off)");
}
Loading
Loading