Update docs; Fix clearing import

Terrain3D.vcxproj

@@ -198,6 +198,7 @@
     <None Include="doc\docs\nightly_builds.md" />
     <None Include="doc\docs\press.md" />
     <None Include="doc\docs\data_format.md" />
+    <None Include="doc\docs\heightmaps.md" />
     <None Include="doc\docs\texture_painting.md" />
     <None Include="doc\docs\user_interface.md" />
     <None Include="doc\index.rst" />

Terrain3D.vcxproj.filters

@@ -238,6 +238,9 @@
     <None Include="project\addons\terrain_3d\extras\minimum.gdshader">
       <Filter>4. Shaders</Filter>
     </None>
+    <None Include="doc\docs\heightmaps.md">
+      <Filter>2. Docs</Filter>
+    </None>
   </ItemGroup>
   <ItemGroup>
     <Text Include=".readthedocs.yaml">

doc/api/class_terrain3d.rst

@@ -1104,13 +1104,13 @@ The main caveats of using this mode is that the call to get_intersection() reque
 
 
 
-This mode can also be used by your plugins and games, such as a space ship firing lasers at the terrain and causing an explosion at the hit point. However if the calls aren't continuous, you'll need to call once to capture the viewport image, wait for it to be drawn, then call again to get the result:
+This mode can also be used by your plugins and games, such as a space ship firing lasers at the terrain and causing an explosion at the hit point. However if the calls aren't continuous, eg driven by the mouse, you'll need to call once to capture the viewport image, wait for it to be drawn, then call again to get the result:
 
 ::
 
-    var target_point = terrain.get_intersection(camera_pos, camera_dir)
+    var target_point = terrain.get_intersection(camera_pos, camera_dir, true)
     await RenderingServer.frame_post_draw
-    target_point = terrain.get_intersection(camera_pos, camera_dir)
+    target_point = terrain.get_intersection(camera_pos, camera_dir, true)
 
 
 

doc/docs/games.md

@@ -14,10 +14,11 @@ Terrain3D is being used in the following games. To add yours, submit it to the #
 | [Pest Apocalypse](https://store.steampowered.com/app/2506810/Pest_Apocalypse/) | [Kikimora Games](https://x.com/KikimoraGames) | Post-apocalyptic pizza delivery
 | [Forg](https://store.steampowered.com/app/2807130/Forg/) | [Crow Games](https://www.youtube.com/@crowgamesdev) | FPS tower defense
 | [open-fpsz](https://gitlab.com/open-fpsz/open-fpsz) | [anyreso](https://mastodon.gamedev.place/@anyreso) | Open-source, Tribes-like FPS multiplayer shooter
+| [Element](https://devanew.itch.io/element) | [Luke Aaron](https://www.youtube.com/watch?v=b18jDnY1YS4) | Gamejam FPS tactial shooter
 
-## Tech Demos
+## Demos
 
 | Game | Studio | Description |
 |------|--------|-------------|
-| [Landscape Demo](https://github.com/OverfortGames/LandscapeDemo) | [Overfort Games](https://x.com/OverfortGames) | Island demo w/ source
+| [Island Demo](https://github.com/OverfortGames/LandscapeDemo) | [Overfort Games](https://x.com/OverfortGames) | Island demo w/ source
 | [Jungle Demo](https://wrobot.itch.io/jungledemo) | [WrobotGames](https://x.com/wrobot123) | Godot rendering demo in a jungle

doc/docs/heightmaps.md

@@ -0,0 +1,112 @@
+Heightmaps
+===========
+
+Terrain3D can be used with pre-made heightmaps. They can be found online, created from heightmap generators, or downloaded from real world data.
+
+Once you have your heightmap source, ensure it is 16 or 32-bit, scaled properly (below), and converted to EXR. Then read [Importing Data](import_export.md) to learn how to import it. What is not covered here is how to convert images in Photoshop, Krita, or Gimp, but you can find tutorials on YouTube.
+
+**Table of Contents**
+* [Pre-made Heightmaps](#pre-made-heightmaps)
+* [Heightmap Generators](#heightmap-generators)
+* [Real World Data](#real-world-data)
+* [Converting Data](#converting-data)
+* [Scaling](#scaling)
+
+
+## Pre-made Heightmaps
+
+A simple web search for `download terrain heightmaps` will allow you to find heightmaps in a few minutes. Some pages might say `free heightmaps for Unity` or `Unreal Engine`. All of these will work. You need to understand what format they are giving you, ensure it is at least 16 or 32-bit, and [convert](#converting-data) that to EXR for import. 
+
+There are also asset packs for game engines like Unreal Engine or Unity that come with premade heightmaps. Both engines provide the ability to export these to a format you can use elsewhere. Be sure to verify the license of the content you're using, but generally anything you've bought can be modified and used elsewhere.
+
+
+## Heightmap Generators
+
+You can use software to generate heightmaps, and in some cases, texture layout maps (aka splat maps, index maps, or our word: control maps). You must look through the documentation of your program to determine what formats and bit depth they export, and convert if necessary.
+
+### Free or Open Source
+
+Search github for `heightmap generator` or `noise generator` to see the current projects. Anything that can produce *and* export a 16-bit grayscale image will work. Here are some examples.
+
+* [wgen](https://github.com/jice-nospam/wgen) - MIT License. Written in Rust. Exports to 16-bit PNG or EXR.
+
+* [HTerrain](https://github.com/Zylann/godot_heightmap_plugin) - MIT License. A GDScript based terrain system for Godot. It includes a terrain generator that can save a heightmap as a native Godot .res file, or you can export to EXR. Both will work for Terrain3D.
+
+* In the future, Terrain3D will include a generator. Follow [Issue 101](https://github.com/TokisanGames/Terrain3D/issues/101) for progress.
+
+
+### Commercial Software
+
+Some of these tools are free for non-commercial use. Generally they generate both heightmaps and control maps. Currently you can only import the heightmaps into Terrain3D.
+
+Importing a control map is possible, but requires you or a contributor to 1) research and document the proprietary control map format available in each tool, 2) create a conversion script for our importer. As programming tasks go, this is pretty easy to do. See [issue 135](https://github.com/TokisanGames/Terrain3D/issues/135) if you'd like to help with one or both.
+
+You could export a baked image of the textures, like a satellite image and import that on our color map, and enable `Debug Views / Colormap`. This could aid you in manual texturing, or left for display purposes.
+
+* [Gaea](https://quadspinner.com/)
+
+* [World Machine](https://www.world-machine.com/)
+
+* [World Creator](https://www.world-creator.com/)
+
+* [Houdini](https://www.sidefx.com/products/houdini/) - General procedural modeling software that includes terrain generation.
+
+* [Instant Terrain](https://www.wysilab.com/) - Terrain generation plugin for UE or Houdini.
+
+
+## Real World Data
+
+There are some websites that allow you to download a heightmap from real world data, however often they are unusable 8-bit heightmaps. These sites might provide usable data:
+
+* https://manticorp.github.io/unrealheightmap/ - exports 16-bit PNGs
+* https://touchterrain.geol.iastate.edu/ - exports GeoTiff
+
+Geographic Information System (GIS) professionals use real world world height data from satellite and aircraft mapping. Much of it is available for free from government websites. This data is often referred to as a Digital Elevation Model (DEM), or Surface (DSM) or Terrain (DTM). A DSM might contain buildings, DTM only the ground, while DEM is the umbrella term. This data may come in a variety of formats.
+
+Example sources:
+
+* [USGS](https://www.usgs.gov/the-national-map-data-delivery/gis-data-download) provides several tools to download DEMs and Tiffs for the US down to 1m resolution.
+* [European Space Agency Copernicus program](https://ec.europa.eu/eurostat/web/gisco/geodata/digital-elevation-model/copernicus) provides DEMs for the whole world.
+* [EU-DEM](https://ec.europa.eu/eurostat/web/gisco/geodata/digital-elevation-model/eu-dem) has tiff files.
+* http://www.terrainmap.com/rm39.html - Here's a list of other websites with GIS data.
+
+There are many sources available online.
+
+Some GIS data might include sattelite imagery. You can import that into our color map, and enable `Debug Views / Colormap`.
+
+
+## Converting Data
+
+Hopefully the GIS data you downloaded will be a 16-bit PNG or GeoTiff (tiff) file. If not, you can try converting it with [VTBuilder](http://vterrain.org/). Drag the file in to the window, and if it loads, use `Elevation/Export To` and save it as 16-bit PNG or GeoTiff.
+
+Godot cannot load either 16-bit PNG or Tiff files, but you can convert both in Photoshop, Gimp, or Krita to EXR. Search YouTube tutorials for instruction in these programs.
+
+Once the source file is opened, the map might show only an outline of your landscape, with the land in white or red, and the ocean in black. You can use the dropper to look at the values, which should all be far above 1. This is a map with real world values. You can use tone mapping to view the image as a gradient heightmap, however you don't want to save it this way.
+
+If the file shows a smooth gradient heightmap, then it's normalized, with all values between 0 and 1. Ensure it is 16 or 32-bit. 8-bit will give you an ugly terraced terrain and will require a lot of smoothing to be usable.
+
+Either normalized or not is fine, as long as you understand how your data is formatted and what scale it should be at.
+
+Save the file as EXR and import into Terrain3D. 
+
+
+### Scaling
+
+Terrain3D generally expects a ratio of 1px = 1m lateral space with real world heights, and provides options for manipulating these. In order to get expected results on import, there are two important characteristics you need to understand about your data:
+
+1. **Vertical Scale**. If your data is not normalized, your data has real values and vertical scale should remain 1 on import. Most likely 0 is defined as sea level. This is how Terrain3D stores data internally. If your data is normalized with values 0-1, you can multiply by a vertical scale in the import tool to set the peak height according to what your source defines. You can also apply an offset to adjust how your data aligns with 0.
+
+2. **Vertical Aspect Ratio (VAR)**. This is often called `resolution` in GIS and terrain documentation, but there is a crucial distinction from image resolution. Your data has an inherent ratio of lateral space to height, or a 3D aspect ratio of XZ to Y. Terrain3D expects 1px = 1m with real world heights, giving a VAR of 1m lateral to 1m vertical. If your data is 1px = 10m with real world heights, the VAR is 10:1, different by a factor of 10. This can be adjusted by scaling the heightmap image in Photoshop before import (preferred), or scaling the heights on import, or adjusting [Mesh / Vertex Spacing](../api/class_terrain3d.html#class-terrain3d-property-vertex-spacing) on or after import.
+
+Here are some examples of adjusting settings to account for both of these both of these characteristics. These examples will be more meaningful if you have read the [import doc](import_export.md) and have imported at least one heightmap first.
+
+* **Ex 1**: You downloaded GIS data that is a 20m resolution DEM. Upon loading the Tiff in Photoshop, the dropper tool reveals that sea level is at 0 and other points on land have real world values in meters. This means the vertical scale is built in, and every 1px on the map represents 20m of lateral space, which represents our VAR of 20:1. You want to work with this map in Terrain3D at the default resolution of 1px = 1m.
+  * **Option 1**: In Photoshop you crop the image down to a small 500x500px area that you want, then scale the image 20x to 10k x 10k. Given the large image size, in Terrain3D you increase the region size to 512 (10k / 32 = 312.5 minimum). (Read [why 32](introduction.md#regions)). Next you import with a scale of 1, offset of 0, and leave vertex_spacing at 1. You now have an accurate representation of the data within Terrain3D that you can sculpt and refine with the standard vertex spacing. You're consuming the VRAM required for a 10k x 10k heightmap. A lot of that is wasted if you do nothing else, since you duplicated the pixels 20x without adding any new data. However this process has given you an accurate base to start sculpting and adding your own detail at a reasonable resolution.
+  * **Option 2**: You import the original image with scale set to 0.05 (1/20th). Now in Terrain3D you have a visually accurate representation of the data, given that the VAR is correct. However if you were to measure the heights, they would be 1/20th their real world values. 1px = 20m and height = 1/20th. There's no wasted VRAM due to duplication of pixels.
+  * **Option 3**: You import the image with a scale of 1. In Terrain3D, it will look very spiky. You increase vertex_spacing to 20. Like the option above, there's no wasted VRAM. This gives you accurate heights, but the world might look a bit low poly.
+
+* **Ex 2**: You exported a heightmap from a commercial tool and received 4 tiled 1024x1024 heightmaps. Upon opening them in Photoshop, they look like gradient heightmaps and the dropper tool confirms the data is normalized with values between 0-1. You were informed the lowest trough is -500m, highest peak 1500m, sea level is 0, and the resolution is 4px to 1m.
+  * **Option 1**: In Photoshop, combine the four tiles into one 4k image. Then scale the whole image by 4 to 16k. On import to Terrain3D, change region size to 512. Set offset to -500m. Set scale to 2000m (1500m - -500m). Change vertex_spacing to 0.25. You now have an accurate representation of the data, and are consuming the VRAM for a 16k x 16k map for a high resolution 4k x 4k world. 0.25m is probably overkill and the increased vertex density does have a performance cost.
+  * **Option 2**: After combining and scaling the images into one 16k image, scale the resolution down to 4k. This erases data between each meter. On import, repeat the region size, offset, and scale as above, but leave vertex_spacing at 1. You still have a 4k x 4k world, with an accurate scale and VAR, but now your terrain resolution is a more optimal 1m. You could also split the difference with a 0.5 or 0.667 vertex_spacing.
+
+Read [Importing Data](import_export.md) to learn how to import your EXR.