AutoHaze — Real-World Atmospheric Haze Correction for X-Plane 12

Requires: FlyWithLua NG | X-Plane 12 | Free API keys for Live mode

---

The Problem

X-Plane 12's atmospheric scattering system bases its haze levels on METAR visibility data. The trouble is that METARs cap visibility at 9,999 metres (metric) or 10SM (US). These values mean "visibility is at least this far", not that visibility is genuinely limited. X-Plane reads these caps literally and sets turbidity (haze) accordingly, resulting in a permanently hazy sky even on clear days. This is a known limitation of the METAR format, not a bug Laminar can easily fix.

AutoHaze corrects this by directly overriding the three private scattering datarefs that control how the atmosphere looks:

• override_turbidity_t — haze density
• single_rat — single scattering (sun-side glare)
• multi_rat — multi scattering (ambient sky colour)

---

Four Modes

Manual — Full slider control over all three values. Two checkboxes link single and multi to turbidity automatically, scaling glare and sky colour naturally as haze changes.

Random — Turbidity wanders randomly between 120 and 300, changing by ±20% every 2–5 minutes with smooth gradual transitions. Single/multi follow along if auto is ticked. Useful when you want natural-feeling variation without any internet connection.

Real — Reads X-Plane's own weather datarefs every 60 seconds (humidity, dew point spread, wind speed, precipitation, visibility) and calculates a turbidity value from them. Better than Manual but still limited by the METAR cap on clear days.

Live — The main event. Queries real-world weather and atmospheric data every 5 minutes based on your aircraft's actual lat/lon position:

• VisualCrossing (primary, requires free API key) — provides visibility, humidity, dew point, wind and precipitation (these are not set by Autohaze, just read for the haze calculation)
• OpenWeatherMap (fallback, requires free API key) — same data if VC fails
• CAMS via Open-Meteo (optional checkbox, completely free, no key needed). Queries aerosol optical depth (AOD) from the Copernicus Atmosphere Monitoring Service model. AOD directly measures how much atmospheric particles scatter light — essentially the same physical quantity that X-Plane's turbidity represents. When enabled, CAMS provides the turbidity base and VC/OWM weather data is applied on top for humidity, precipitation and wind adjustments.

---

Why CAMS Makes a Difference

Standard weather APIs (including VisualCrossing and OWM) source visibility from METAR stations, which means they hit the same 10-mile / 10km cap as X-Plane. CAMS is different, it's a global atmospheric model that measures aerosol optical depth, which is not subject to the METAR cap and can reflect genuinely clear conditions (AOD 0.05 → ~78km equivalent visibility, versus the METAR maximum of ~16km).

On a clear day over Southern California I was seeing turbidity values around 108–115 using CAMS, compared to 170+ without it. The sky looked noticeably more realistic.

---

Smart Handback

When visibility is genuinely below 9.5km (fog, rain, mist, low cloud), X-Plane's own weather engine already has real METAR data to work with and renders those conditions correctly. In this case AutoHaze gradually releases control of all three datarefs and hands everything back to X-Plane, so the two systems don't fight each other.

---

Installation

1. Install FlyWithLua NG if you haven't already
2. Drop AutoHaze.lua into X-Plane 12/Resources/plugins/FlyWithLua/Scripts/
3. For Live mode, sign up for free API keys:
   • VisualCrossing: https://www.visualcrossing.com/sign-up
   • OpenWeatherMap: https://home.openweathermap.org/users/sign_up
4. On first run, AutoHaze creates AutoHaze-api-keys.txt in the Scripts folder — open it and paste your keys in (line 1: VisualCrossing, line 2: OpenWeatherMap)
5. Open the macro via Plugins → FlyWithLua → FlyWithLua Macros → AutoHaze Settings
6. Press Live, tick Use CAMS aerosol data.
7. Tick the checkboxes next to the Single and Multi sliders to enable automatic sky colour and glare scaling.

---

Notes

• Live mode uses PowerShell for HTTP requests, no additional software needed on Windows 10+
• CAMS data updates every 6 hours; VC/OWM weather adjustments update every 5 minutes
• Single and multi auto mode scales sky colour and glare naturally with turbidity, recommended to leave ticked
• Transitions between turbidity values are always gradual, never instant, to avoid jarring visual changes

Settings (including CAMS preference) are restored automatically on startup from the last manual save.

Edited April 18Apr 18 by MrBitstFlyer

Very interesting but I am unable to create account on openweathermap. Keeps saying something went wrong.

7 minutes ago, Baber20 said:

Very interesting but I am unable to create account on openweathermap. Keeps saying something went wrong.

Odd, I created an account no problem 🤔  Works without OpenWeatherMap as that is a backup if VisualCrossing fails - hasn't failed for me through testing.

Edited April 18Apr 18 by MrBitstFlyer

Users with ortho scenery will notice a particular improvement — X-Plane 12's default excessive haze was effectively desaturating ortho textures and giving them a washed-out appearance. With AutoHaze correcting turbidity to realistic levels, ortho colours come through with their intended vibrancy and the scenery has proper visual depth.

Edited April 18Apr 18 by MrBitstFlyer

This is excellent @MrBitstFlyer !!!

Thank you for making it available to the community 🙏

Wow..this is cool!  It just so happens I stumbled across this right before a flight in XP 12 which I have not done in a couple months.  I was able to get the API for VisualCrossing but I was unable to get the one for OWM like Baber20 mentioned.  I tried it out on a short 1 hour flight and it works well.  I do notice that I get a fairly long pause in the sim when the Live option updates, about 7-8 seconds long.  I switched it back to Manual which held the same values.  I wonder if there is a way to adjust the time between updates maybe to lengthen out the pauses unless it is not supposed to do that...?  Nice job!  On another note, the clouds and lighting were just incredible...I am always amazed when I come back into XP12 for a some flights....

Well done! AutoHaze really does make a difference, and improves on HazeAdjust. Just to clarify, we should paste the API key(s) over the existing text in the txt file?

Like Baber20 and Flic1, I couldn't create an OpenWeatherMap account, but since it's just a fallback, no problem. Thanks very much for producing this.

3 hours ago, Brian Mackie said:

Just to clarify, we should paste the API key(s) over the existing text in the txt file?

That's correct, just make sure you paste on the correct line (line 1: VisualCrossing, line 2: OpenWeatherMap).

Odd OWM is not creating keys - I used it a lot during testing 🤔

9 hours ago, Flic1 said:

I do notice that I get a fairly long pause in the sim when the Live option updates, about 7-8 seconds long.  I switched it back to Manual which held the same values.  I wonder if there is a way to adjust the time between updates maybe to lengthen out the pauses

I have uploaded a new version with a slider to control download interval.  On my PC I get a very brief flash of the Powershell CMD window when the data downloads.  I'll have a think what may be causing a longer pause.

You might want to make it clear on the library page that Live mode is for Windows only. Maybe you can use luasocket (https://w3.impa.br/~diego/software/luasocket/home.html; included as a FlyWithLua module) to make the http calls to the APIs in a more OS agnostic fashion.

Edited April 19Apr 19 by Bjoern

Just now, Bjoern said:

You might want to make it clear on the library page that Live mode is for Windows only. Maybe you can use luasocket (https://w3.impa.br/~diego/software/luasocket/home.html; included as a FlyWithLua module) to make the http calls to the APIs in a more OS agnostic fashion.

Thanks for that suggestion 👍

I have uploaded a new verion with an added feature.

Added BLH (Boundary Layer Height).

A call is made to Open-Meteo Forecast API to obtain the correct boundary layer height for your location. Haze is concentrated into this layer so as you climb, visibility will improve, the sky will brighten and turn more blue. Distant clouds and terrain will became visible. When descending into the haze layer, haze will increase, the sky will turn less blue and darken. So if your destination is reporting haze, you will now descend into it! Sometimes XP12 doesn't report visibility and haze correctly, so check the override XP12 button for correct visibility. There is also a checkbox so you can set your own BLH (good if you don't want the extra API call). For example if you want to test it you can set a BLH at 2000ft - the real BLH maybe a lot higher.

If the visibility is low and the haze high, you will get much reduced visibility, but you can climb out of it! If you are maintaining altitude around the BLH height and the sky is clear, you will see blue sky above and a dirty haze layer visible on the horizon. A very good airport to test this is VEPT in India. Set a fixed BLH of 3,000ft for a very grey airport environment, but take off and see the conditions improve as you climb!

Edited April 19Apr 19 by MrBitstFlyer

Working well with the latest changes, but it would be good to hide the Powershell calls. They're a little distracting.

@MrBitstFlyer I think you can spawn a powershell window as hidden (so negating the flashing window) by doing the following (if I remember correctly):

conhost -headless "powershell.exe -yourcommandlinehere"

Maybe that will help?

11 hours ago, Brian Mackie said:

Working well with the latest changes, but it would be good to hide the Powershell calls. They're a little distracting.

For me I get a very brief flash which I find acceptable for the added features. However, some are reporting longer for Powershell to complete the API calls.  You could check the following.

Windows Defender real-time scanning. Defender may be scanning each PowerShell process as it launches, adding 2–4 seconds per call. Add the FlyWithLua Scripts folder to Defender exclusions: Windows Security → Virus & threat protection → Manage settings → Exclusions → Add folder
Navigate to X-Plane 12/Resources/plugins/FlyWithLua/Scripts/ and add it.

PowerShell profile loading. If you have a PowerShell profile configured it loads on every launch, adding startup time. AutoHaze already uses -NonInteractive but some profile configurations still load. Try adding -NoProfile to the PowerShell command.

Would be useful to know if these suggestions reduce the time it takes for Powershell to complete on your system.