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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,4 @@ artifacts/
TestResults/
.vscode
site/
.claude
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@ Source layout under `src/OrthoStreamXP/`. Sub-folders are for navigation only: *
- `Paging/`: `PagingModel`, `PagingMeasurements`, `PagingCalibration`.
- `Prefetch/`: `LoadAheadPrefetcher`, `PrefetchPlanner`, `MipWarmer`.
- `Aircraft/`: `AircraftPositionListener` (X-Plane UDP), `ViewTracker`, `SceneryLoads`.
- `Colour/`: `ColourMatcher` (evens patchwork), `SeasonClock` (seasonal tint by simulated date/location).
- `Textures/` — imagery to DDS: `TextureBuilder` (fetch → stitch → resize → mipmaps → BC1 encode → atomic write; own encoder, SkiaSharp is decode-only), `TextureQuality`, `Images` at the root; `Tiles/` (`TileSource`/`TileStore`: download + cache), `Dds/`, `Scheduling/` (priority gates), `Seasons/`, `Colour/` (`ColourMatch`, `Exposure`, `ColourTable` = the shared BC1 lookup-table recolouring, `PhotoColours` = match → season → exposure as X-Plane reads, also used by the Settings preview).
- `Colour/`: `SeasonClock` (seasonal tint by simulated date/location), `ObservedSeasons` (loads the satellite record per ~500 km tile for `season = satellite`).
- `Textures/` — imagery to DDS: `TextureBuilder` (fetch → stitch → resize → sharpen → mipmaps → BC1 encode → atomic write; SkiaSharp is decode-only), `TextureQuality`, `Images`, `Sharpening` (unsharp mask on brightness, not a setting: 100 % for the areas' textures below ZL18, 60 % for the airports' ZL18 and finer) at the root; `Tiles/` (`TileSource`/`TileStore`: download + cache; the low-zoom base is zoom 13 and coarser because Bing's zoom 12 is other, lighter imagery; a tile every provider definitively lacks throws `TileNotAvailableException`, and `TextureBuilder` then makes it from a parent at hand, never coarser than 13), `Dds/` (`Dds` layout/encode/decode; mip levels by `MipFilter` = 2x2 averages in linear light; BC1 by `IspcBc1` = Intel's ISPC `ispc_texcomp.dll` from `native/ispc_texcomp/` (checked in, rebuilt by its `build.ps1`), loaded from the exe's folder, with one-colour blocks and four-colour mode fixed after it and every other block's colours refined by least squares (`Bc1Refinement`); `Dds.EncodeRangeFit` is the fallback without the DLL), `Scheduling/` (priority gates), `Seasons/` (`SeasonModel` calendar, `ObservedSeason` + `GreennessYear`: grass and fields by a place's yearly NDVI against its greenest month, trees by the calendar), `Vegetation/` (`VegetationSource`: NASA GIBS monthly VIIRS NDVI, downloaded and kept under the low-zoom base; `VegetationTile`, `NdviPalette`), `Colour/` (`Exposure`, `Contrast` (fixed 60 % S-curve, always on, not a setting), `ColourTable` = the shared BC1 lookup-table recolouring, `PhotoColours` = season → contrast → exposure as one table (rounded to 565 once) applied as X-Plane reads, also used by the Settings preview).
- `Setup/` — `Settings/` (`SettingsDocument`, ini under `%LOCALAPPDATA%\OrthoStreamXP`, `QualityPreset`, `ConnectionTest`), `Cache/` (inventory, areas, eviction), `Packages/` (downloads AutoOrtho's mesh regions from GitHub into the packages folder as `OrthoStream_*` packages: `MeshCatalog`, `AssetDownload`, `ZipUnpacker`, `OverlayPackage`, `RegionInstaller`), `Installation/` (`AppPaths`, `AppUpdates`, `LegacyNames` migrating older settings/cache locations, `SystemCheck`, Velopack hooks).
- `Tuning/` — flight reports, facts and the preset/setting recommendations.
- Logs go to `%LOCALAPPDATA%\OrthoStreamXP\logs`.
Expand Down
17 changes: 11 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,14 @@ Traditional photo scenery often requires downloading and building large areas be
- **Less disk space wasted** — keep the areas you fly and automatically remove older scenery when your cache reaches its limit.
- **Better scenery ahead** — OrthoStreamXP follows your aircraft and downloads upcoming areas before you reach them.
- **Simple quality settings** — choose Balanced, Sharp, Ultra, or Extra without learning dozens of technical parameters.
- **Sharp, crisp textures** — up to 8192 px, keeping all the detail of the imagery, sharpened a little and given a touch of contrast, as aerial photos are often hazy.
- **Settings that adapt to your setup** — test your connection before the first flight to get a recommended preset, and after a sufficiently long flight, get recommendations based on how the scenery performed on your PC and internet connection. You decide whether to apply them.
- **Even colours** — optionally soften the patchwork look where neighbouring photos were taken on different days, so a grey, hazy patch stands out less.
- **Seasonal colours** — optionally give summer imagery a more autumnal or winter appearance, based on the simulated date and location.
- **Seasonal colours** — optionally give summer imagery a more autumnal or winter appearance, based on the simulated date and location, with grass and fields optionally coloured by NASA's satellite record of how green each place really was.
- **Clean photos up close** — X-Plane's procedural grass and dirt speckles are kept off the aerial photos by default, or faded to the strength you like, without changing your scenery packages.
- **Towns lit at night** — optionally give the photo scenery street lamps and the light of the houses along X-Plane's roads, so towns glow after dark as on X-Plane's own scenery. You can also skip the detailed photos at night to save downloads, keeping the lights.
- **Exposure and a live preview** — tone down photos that look too bright next to X-Plane's own scenery, and see any colour change on a photo from your cache before you fly.
- **See what happened during your flight** — review download performance, scenery loading, and your flight route.
- **Your scenery list, without Notepad** — switch X-Plane's scenery packages on or off and drag them into order on the X-Plane Custom Scenery page, and leave any of your photo scenery packages out of a flight with one switch on the Home page.

### Designed for everyday flying

Expand Down Expand Up @@ -87,7 +88,9 @@ OrthoStreamXP provides five presets:
- **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.
- **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. Its **Base** can be Ultra or Sharp instead of Extra, for a slower connection.

Each preset also has a **Resolution**: **Full** keeps all the detail of the imagery, **Medium** halves the textures away from airports and **Low** halves them all, to fit a smaller graphics card from the same imagery.

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 All @@ -98,7 +101,7 @@ After flights of at least 10 minutes, OrthoStreamXP may suggest adjustments base
The Cache page helps you manage the imagery stored on your computer.

- Set a cache limit from 25 GB up to 1 TB.
- View cached areas on a map.
- View cached areas on a full-width map you can zoom and drag.
- Select and delete areas you no longer need.
- Identify areas you have not flown over recently.

Expand All @@ -108,7 +111,7 @@ When the cache exceeds its limit, OrthoStreamXP removes older areas automaticall

Most aerial imagery was captured during warmer months, so a winter flight can otherwise look unexpectedly green.

Enable **Seasons** to adjust the appearance of vegetation and fields according to X-Plane's simulated date and the location you're flying over.
Turn on **Colour the scenery for the season** (Settings › Colours) to adjust the appearance of vegetation and fields according to X-Plane's simulated date and the location you're flying over.

- **Spring:** fresh greens return.
- **Summer:** the imagery as it was photographed.
Expand All @@ -117,6 +120,8 @@ Enable **Seasons** to adjust the appearance of vegetation and fields according t

Water, roads, buildings, rock, and sand retain their original colours. Seasonal colouring does not generate snow; snow remains part of X-Plane's weather.

Choose **Satellite** as the season to colour the grass and fields by NASA's satellite record of the last year instead of the calendar alone: Atlantic and Mediterranean coasts stay green in a mild winter, fields dry out in a dry summer, and the tropics show their dry season. Trees keep the calendar. It downloads about 2 MB once a year for each area of about 500 km you fly over.

## Known limitations

OrthoStreamXP is currently in beta. Please keep the following in mind:
Expand All @@ -131,7 +136,7 @@ OrthoStreamXP is currently in beta. Please keep the following in mind:

## Imagery and licensing

OrthoStreamXP is free software released under the **GNU General Public License v3 (GPL-3.0)**.
OrthoStreamXP is free software released under the **GNU General Public License v3 (GPL-3.0)**. It includes Intel's [ISPC Texture Compressor](https://github.com/GameTechDev/ISPCTextureCompressor) (MIT) to encode textures.

The aerial imagery is provided by external services, including Bing Maps, Esri World Imagery, and Geoportal for Poland. The imagery is not part of the OrthoStreamXP software and remains subject to each provider's terms of use.

Expand Down
2 changes: 1 addition & 1 deletion build-user-guide.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ if (-not $browser) { throw 'Google Chrome or Microsoft Edge is needed to print t

# The order of the guide's contents (docs\README.md). The pages keep their names so that pandoc's --file-scope
# turns the links between them (settings.md#quality) into links inside the PDF.
$pages = 'README', 'installation', 'first-setup', 'flying', 'settings', 'cache', 'packages', 'troubleshooting', 'faq'
$pages = 'README', 'installation', 'first-setup', 'flying', 'settings', 'cache', 'packages', 'custom-scenery', 'troubleshooting', 'faq'
$work = 'artifacts\user-guide'
if (Test-Path $work) { Remove-Item $work -Recurse -Force }
New-Item -ItemType Directory $work | Out-Null
Expand Down
Binary file modified docs/OrthoStreamXP-UserGuide.pdf
Binary file not shown.
5 changes: 3 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ OrthoStreamXP adds real-world aerial photos to your X-Plane 12 scenery while you
4. [Settings](settings.md): quality and ground detail, folders, downloads, colours, seasons and exposure, night lights and photos at night.
5. [Cache](cache.md): how much disk space the scenery uses and how to free it.
6. [Packages](packages.md): downloading the ground mesh of a whole region, the quickest way to get scenery packages.
7. [Troubleshooting](troubleshooting.md): common problems, the log, updates, uninstalling and reporting a bug.
8. [Questions and answers](faq.md): what OrthoStreamXP does and does not do, choosing the packages folder, switching from AutoOrtho.
7. [X-Plane Custom Scenery](custom-scenery.md): switching X-Plane's scenery packages on or off and changing their order.
8. [Troubleshooting](troubleshooting.md): common problems, the log, updates, uninstalling and reporting a bug.
9. [Questions and answers](faq.md): what OrthoStreamXP does and does not do, choosing the packages folder, switching from AutoOrtho.

## The short version

Expand Down
6 changes: 5 additions & 1 deletion docs/cache.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ The cache holds the pictures OrthoStreamXP downloads and the textures it builds.

The map shows each 1° × 1° area you have flown, pictured from its own textures. Faded squares were not flown for a month; the cache limit removes those first.

The map uses the full width of the window. Scroll to zoom in and out around the pointer, and drag to move the map. The buttons at its side zoom in, zoom out and **Show all areas**. Latitude and longitude lines, labelled along the top and left edges, help you find a place; they come closer together as you zoom in.

To free space by hand:

1. Click the areas you want to remove, or click **Select not flown for a month**.
Expand All @@ -32,10 +34,12 @@ Areas can be deleted only while OrthoStreamXP is stopped, because X-Plane may be
Each quality preset keeps its textures in its own folder, so switching presets never throws textures away. This list shows how much each one takes:

- **One row per preset you have flown with** (for example *Extra*), with its texture sizes and number of files. The preset you use now is marked **In use**. Delete a preset you no longer use to free its space.
- A preset used at a lower [resolution](settings.md#resolution) keeps those textures in a folder of their own, listed as, for example, *Ultra, Medium resolution*.
- When an update changes a preset's texture sizes (as 1.5.0 did), the textures built before it stay in their old folder. They are listed as a second row for the same preset, with the old sizes, and OrthoStreamXP no longer uses them, so you can delete that row.
- **Low-zoom base:** coarse pictures that distant scenery is drawn from. All presets share it. If you delete it, distant scenery is a plain colour at the start of a flight until these pictures are downloaded again.
- **Logs:** the log files of earlier runs.
- A folder left by an older version of OrthoStreamXP, from before each preset had its own folder, is listed too. OrthoStreamXP no longer uses it, so you can delete it.

Each row has a folder button that opens it in Explorer and a bin button that deletes it after you confirm.

Next: [Troubleshooting](troubleshooting.md)
Next: [Packages](packages.md)
40 changes: 40 additions & 0 deletions docs/custom-scenery.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# X-Plane Custom Scenery

[User guide](README.md) › X-Plane Custom Scenery

X-Plane keeps a list of its scenery packages in `Custom Scenery\scenery_packs.ini`. A package higher in the list covers the ones below it: an airport above the photo scenery is drawn on top of the photos. The **X-Plane Custom Scenery** page in the sidebar shows this list, so you can change it without editing the file by hand.

![The X-Plane Custom Scenery page](images/custom-scenery.png)

## The list

- The packages are listed in the file's order, **highest priority first**; the line above the list names the file. Under each name is its folder.
- While OrthoStreamXP runs, the packages it shows to X-Plane are marked **OrthoStreamXP**.
- The page needs the **X-Plane folder** to be set in [Settings › Folders](settings.md#folders); until then it says *Choose your X-Plane folder first*. If X-Plane has never started with this folder, the list is empty: X-Plane writes the file the first time it starts.
- **Open the folder** opens X-Plane's `Custom Scenery` folder in Explorer. **Refresh** reads the file again, for example after you installed scenery while the page was open.

## Switching packages on or off

The switch at the end of each row turns a package on or off in X-Plane. A package switched off stays in its folder and in the list; X-Plane just does not load it. This is the same as X-Plane's own `SCENERY_PACK_DISABLED` lines in the file.

## Changing the order

Drag a package by the handle at the start of its row and drop it where you want it: the other rows move apart to show where it lands. Higher in the list means drawn on top.

Leave the photo scenery near the end, below airports and overlays. With **Keep the photo scenery below airports and overlays** on (see [Settings › Other](settings.md#other)), OrthoStreamXP moves its packages back to the end at every start anyway.

## When changes apply

- The list can be changed **only while OrthoStreamXP is stopped**: starting and stopping change the file too. While it runs, the page says *OrthoStreamXP is running: stop it to change the list.* It shows the list as it is, with the switches greyed out and no drag handles.
- X-Plane reads the list when it starts, so a change shows from **X-Plane's next start**.
- Every change is written straight into `scenery_packs.ini`. The other lines of the file stay as they are.

![The list while OrthoStreamXP runs: its packages are marked OrthoStreamXP and the list cannot be changed](images/custom-scenery-running.png)

## The packages OrthoStreamXP adds

When you click **Start**, OrthoStreamXP adds its packages to the end of the list. When you click **Stop**, it takes out again the ones it added, because their folders are gone from `Custom Scenery` until the next start. A package that was already in the list before the start (for example from an earlier version of OrthoStreamXP) stays where it is.

To leave one of your own scenery packages out of OrthoStreamXP's photo scenery, use its switch under **Scenery packages** on the Home page instead (see [Flying › Leaving a package out](flying.md#leaving-a-package-out)).

Next: [Troubleshooting](troubleshooting.md)
8 changes: 5 additions & 3 deletions docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Each scenery file (`.dsf`) says exactly which photo texture goes on which part o
All three put photos on scenery packages, so the base packages are the same. OrthoStreamXP was written to avoid the problems of the others:

- **Speed.** A new area loads in a few minutes (each preset card shows an estimate), and areas you have flown before load from the cache at once.
- **Quality for free.** There is no paid tier. Textures go up to 4096 px and the imagery up to zoom 19, with no limit on the zoom level or the picture size.
- **Quality for free.** There is no paid tier. Textures go up to 8192 px and the imagery up to zoom 19, with no limit on the zoom level or the picture size.
- **Settings tuned for you.** **Test my connection** chooses the quality and the number of downloads, and after each flight OrthoStreamXP suggests changes from what it measured (see [Flying](flying.md#tuning-suggestions)).

### I already have ZL17/ZL18 photo scenery on disk. What do I gain?
Expand Down Expand Up @@ -81,7 +81,7 @@ No. Move them anywhere else on your PC, for example `D:\OrthoPackages`. OrthoStr

1. Close AutoOrtho.
2. Move your AutoOrtho scenery packages out of `X-Plane 12\Custom Scenery` to any folder on your PC.
3. Open `X-Plane 12\Custom Scenery\scenery_packs.ini` and remove the lines for the AutoOrtho packages.
3. Open `X-Plane 12\Custom Scenery\scenery_packs.ini` and remove the lines for the AutoOrtho packages. If you would rather not edit the file, switch them off on OrthoStreamXP's [X-Plane Custom Scenery](custom-scenery.md) page instead.
4. Open OrthoStreamXP **without** starting the scenery. In **Settings › Folders**, set the **Scenery packages folder** to the new place.
5. Click **Start and fly** (or **Start**, then start X-Plane).

Expand All @@ -90,7 +90,9 @@ No. Move them anywhere else on your PC, for example `D:\OrthoPackages`. OrthoStr
1. Your packages appear in `X-Plane 12\Custom Scenery`, with the photos added. The packages on disk stay unchanged.
2. OrthoStreamXP adds them to the end of `scenery_packs.ini`, so airports and overlays stay above them. The previous file is kept as `scenery_packs.ini.bak`.

When you stop OrthoStreamXP, the packages disappear from `Custom Scenery` again.
When you stop OrthoStreamXP, the packages disappear from `Custom Scenery` again, and the lines it added to `scenery_packs.ini` at the start are taken out.

Packages switched off under **Scenery packages** on the Home page are left out (see [Flying › Leaving a package out](flying.md#leaving-a-package-out)).

### It downloaded a few pictures and then nothing, and the ground looks like X-Plane's own scenery.

Expand Down
Loading
Loading