diff --git a/Terrain3D.vcxproj b/Terrain3D.vcxproj index dbd8465c..96f56f7d 100644 --- a/Terrain3D.vcxproj +++ b/Terrain3D.vcxproj @@ -198,6 +198,7 @@ + diff --git a/Terrain3D.vcxproj.filters b/Terrain3D.vcxproj.filters index f8310fc6..7e0e5f0f 100644 --- a/Terrain3D.vcxproj.filters +++ b/Terrain3D.vcxproj.filters @@ -238,6 +238,9 @@ 4. Shaders + + 2. Docs + diff --git a/doc/api/class_terrain3d.rst b/doc/api/class_terrain3d.rst index 35b0a22e..3b8a9f54 100644 --- a/doc/api/class_terrain3d.rst +++ b/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) diff --git a/doc/docs/controlmap_format.md b/doc/docs/controlmap_format.md index 957f31ed..1517673b 100644 --- a/doc/docs/controlmap_format.md +++ b/doc/docs/controlmap_format.md @@ -21,6 +21,7 @@ We process each uint32 pixel as a bit field with the following definition, start * We use a FORMAT_RF 32-bit float Image or Texture to allocate the memory. Then in C++, we read or write each uint32 pixel directly into the "float" memory. The values are meaningless when interpreted as floats. We don't convert the integer values to float, so there is no precision loss. Godot shaders support usamplers so we can interpret the memory directly as uint32, without requiring any conversion. * Gamedevs can use the conversion and testing functions found in Terrain3DUtil defined in [C++](https://github.com/TokisanGames/Terrain3D/blob/main/src/terrain_3d_util.h) and [GDScript](../api/class_terrain3dutil.rst). * Possible future plans for reserved bits: + * 2 bits - Hole and Navigation might be stored elsewhere, freeing up 2 bits * 5 bits - 32 paintable particles * 3 bits - paintable slope array index+ * 2 bits - 4 layers (including Hole above, eg water, non-destructive, hole, normal mesh) diff --git a/doc/docs/games.md b/doc/docs/games.md index ab1fb01c..b47dbef9 100644 --- a/doc/docs/games.md +++ b/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 diff --git a/doc/docs/heightmaps.md b/doc/docs/heightmaps.md new file mode 100644 index 00000000..219bcab5 --- /dev/null +++ b/doc/docs/heightmaps.md @@ -0,0 +1,146 @@ +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` or `16`. Then read [Importing Data](import_export.md) to learn how to import it. What is not covered here is how to use 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/) + +* [Terragen](https://planetside.co.uk/) + +* [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 + +Converting data is not trivial. Understanding how your data is stored and how to convert it to another format is an essential skill for you to learn. + +Ultimately we want the data stored as an `exr` or `r16` for import into Terrain3D. See [supported formats](import_export.md#supported-formats) for more details. + +How we get there depends on your source data and tools available. Photoshop, Krita, or Gimp are the most common tools, but you might find others or even write scripts in python to convert data. How to use these tools is out of scope for this documentation. You might need to work through multiple tools to get the right format and workflow. I promise any time spent learning this will be useful for your entire life working with computers. + + +### File Format + +Hopefully the GIS data you downloaded will be a 16-bit PNG or Tiff/GeoTiff file, which may allow you to convert it directly just by saving the file as an EXR or r16 in Krita. GeoTiff is a Tiff file with geospatial metadata embedded. + +Some Tiff formats are newer and not supported by all image editing apps, and may require experimentation with multiple tools. + +You might be able to convert it with a python script such as the following, which produces an r16 file (named raw): +``` + from PIL import Image + import numpy + + im = Image.open('image.tif') + imarray = numpy.array(im) + imarray.astype('int16').tofile("image.raw") +``` + +If your source data is any other format, you can try converting it with [VTBuilder](http://vterrain.org/). Drag the file into the window, and if it loads, use `Elevation/Export To` and save it as 16-bit PNG or GeoTiff. + + +### Normalized Data + +Once the source file is opened in an image editing program, the map might show only an outline of your landscape, with the land in solid white or red, and the ocean in black. You can use the dropper to look at the values, which should show expected values for heights in meters. 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 the image 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 values or real values are fine, as long as you understand how your data is formatted and that you must scale normalized value on import. That means knowing how much to scale by, which info should be provided with the data source. + + +### Conversion Examples + +* **Ex 1** - I exported a 16-bit PNG from a commercial tool. I opened the file in Photoshop and exported it as EXR. Or I could have opened it in Krita and exported as EXR or R16. + +* **Ex 2** - I downloaded a Digital Elevation Model (DEM) from a govt website and received GeoTiff files. Though I've opened other GeoTiff files in Photoshop before, it decided it couldn't read these. Krita opened them but only displayed black. I was able open them in Gimp, and reviewing the pixel data showed the ocean at `-inf`, and the land at real world values. I exported as EXR and imported to Terrain3D, but the land was extremely high. I was able to open the EXR in Photoshop and compare with my other known working EXR files. The landscape shape appeared, but the height values were extremely large. I experimented with various color management and bit depth conversions within Gimp to see if I could get a correct looking EXR in Photoshop, but couldn't. In Gimp, I exported as Tiff, which gave me what I was looking for in Photoshop, except the ocean still showed `-inf`, which is a problem as it produced holes in Terrain3D, but not our kind of holes that can be filled in. In Gimp I found `Colors / RGBClip` in the menu and used it to limit `-inf` to 0, while retaining height values above 1. Then I exported the Tiff to Photoshop, confirmed the values looked good, ane exported that to EXR for import and finally got the desired result. + + +## 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. + + +### Scaling Examples + +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**: I downloaded GIS data that is a 20m resolution DEM and received a GeoTiff. Upon loading it in Photoshop, the dropper tool revealed 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. I want to work with this map in Terrain3D at the default resolution of 1px = 1m. + * **Option 1**: In Photoshop I crop the image down to a small 500x500px area that I want to import, then scale the image 20x to 10k x 10k. Given the large image size, in Terrain3D I increase the region size to 512 (10k / 32 = 312.5 minimum). (Read [why 32](introduction.md#regions)). Next I import with a scale of 1, offset of 0, and leave vertex_spacing at 1. I now have an accurate representation of the data within Terrain3D that I can sculpt and refine with the standard vertex spacing. This consumes the VRAM required for a 10k x 10k heightmap. A lot of that is wasted if I do nothing else, since I duplicated the pixels 20x without adding any new data. However this process has given me an accurate base to start sculpting and adding my own detail at a reasonable resolution. This is likely my preferred path for real world data. + * **Option 2**: I import the original image with scale set to 0.05 (1/20th). Now in Terrain3D I have a visually accurate representation of the data, given that the VAR is correct. However if I 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. This is a good path if I only want to visualize the data. + * **Option 3**: I import the image with a scale of 1. In Terrain3D, it will look very spiky. I increase vertex_spacing to 20. Like the option above, there's no wasted VRAM. This gives I accurate heights, but the world might look a bit low poly. + +* **Ex 2**: I 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. I was informed the lowest trough is -500m, highest peak 1500m, sea level is 0, and the resolution is 4px to 1m. + * **Option 1**: In Photoshop, I combine the four tiles into one 4k image. Then I scale the whole image by 4 to 16k. On import to Terrain3D, I change region size to 512, set offset to -500m, and scale to 2000m (1500m - -500m). I change vertex_spacing to 0.25. I now have an accurate representation of the data, and am 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, I scale the resolution down to 4k. This erases data between each meter. On import, I repeat the region size, offset, and scale as above, but leave vertex_spacing at 1. I still have a 4k x 4k world, with an accurate scale and VAR, but now my terrain resolution is a more optimal 1m. I 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. diff --git a/doc/docs/import_export.md b/doc/docs/import_export.md index accf4fa8..2bdb2f80 100644 --- a/doc/docs/import_export.md +++ b/doc/docs/import_export.md @@ -1,8 +1,53 @@ Importing & Exporting Data =========================== +This page describes how to import data into our tool. You should read [Heightmaps](heightmaps.md) to learn about preparing files from various data sources. + Currently importing and exporting is possible via code or our import tool. We will [make a UI](https://github.com/TokisanGames/Terrain3D/issues/81) eventually. In the meantime, we have written a script that uses the Godot Inspector as a makeshift UI. You can use it to make a data file for your other scenes. +## Supported Formats + +Terrain3D has three map types you can import or export: [Height](../api/class_terrain3dregion.html#class-terrain3dregion-property-height-map), [Control](../api/class_terrain3dregion.html#class-terrain3dregion-property-control-map), and [Color](../api/class_terrain3dregion.html#class-terrain3dregion-property-color-map). + +We can import any supported image format that Godot can read, however we have recomendations below for specific formats to use for the different maps. + +Supported Import Formats: + +* [Godot supported Image file formats](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_images.html#supported-image-formats): `bmp`, `dds`, `exr`, `hdr`, `jpg`, `jpeg`, `png`, `tga`, `svg`, `webp` +* [Godot resource files](https://docs.godotengine.org/en/stable/classes/class_image.html#enum-image-format): Any data format on the list stored as a `tres` or `res`. +* `exr`: should be RGB, 16 or 32-bit float, linear light. Older versions of Photoshop can use [exr-io](https://www.exr-io.com/). +* `png`: Godot only supports 8-bit PNGs. This works fine for the colormap, but not for heightmaps. +* `r16`: for heightmaps. Values are scaled based on min and max heights and stored as 16-bit unsigned int. Can be read/written by Krita. Min/max heights and image dimensions are not stored in the file, so you must keep track of them elsewhere, such as in the filename. +* `raw`: This is not a format specification! It just means the file contains a dump of values. But what format are the values? They could be 8, 16, or 32-bit, signed or unsigned ints, little or big endian byte order (aka Windows or macOS, Intel or Arm/Motorola). In order to read this file you need to know all of these, *and* the dimensions. `Photoshop Raw` only supports 8/16/32-bit float, little or big endian. **Terrain3D interpret raw as r16**, as does Unity, Unreal Engine, and various commercial software. + +Supported Export Formats: + +* [Godot supported Image save functions](https://docs.godotengine.org/en/stable/classes/class_image.html#class-image-method-save-exr): `exr`, `png`, `jpg`, `webp` +* `r16`: for heightmaps. +* `res`: Godot binary resource file with `ResourceSaver::FLAG_COMPRESS` enabled. The format contained inside is defined in our API linked at the top of this section for each map type. +* `tres`: Godot text resource file. Not recommended. + + +### Height Map Recommendations + +* Use `exr` or `r16/raw`. +* If you have a 16-bit PNG, convert it. +* If your data is only 8-bit, it will look terraced and require a lot of smoothing to be useable. Only use 16 or 32-bit height data. +* [Zylann's HTerrain](https://github.com/Zylann/godot_heightmap_plugin/) stores height data in a `res` file which we can import directly. No need to export it first, though his tool also also exports `exr` and `r16`. + + +### Control Map Recommendations + +* Our control maps use a [proprietary format](controlmap_format.md). We currently only import our own format. Use `exr` to export and reimport only from this tool. This is only for transferring the data to another Terrain3D data file. + + +### Color Map Recommendations + +* Any regular color format is fine. +* `png` or `webp` are recommended as they are lossless, unlike `jpg`. +* The alpha channel is interpretted as a [roughness modifier](../api/class_terrain3ddata.rst#class-terrain3ddata-property-color-maps) for wetness. So if you wish to edit the color map in an external program, you may need to disable the alpha channel first. + + ## Importing Data 1) Open `addons/terrain_3d/tools/importer.tscn`. @@ -13,51 +58,34 @@ Currently importing and exporting is possible via code or our import tool. We wi :target: ../_images/io_importer.png ``` -3) In the inspector, select a file for height, control, and/or color maps. See [formats](#supported-import-formats) below. File type is determined by extension. +3) If you're importing a large file, you need to adjust `Terrain3D / Regions / Region Size`. You only get [1024 regions (32x32)](introduction.md#regions) so you need a region size greater than `image width / 32`. E.g., importing 10k x 10k means 10,000/32 = 312.5, so a minimum region size of 512 is required. + +4) In the inspector, select a file for height, control, and/or color maps. See [formats](#supported-formats) above. File type is determined by extension. -4) Specify the `import_position` of where in the world you want to import. Values are rounded to the nearest `region_size` (defaults to 1024). So a location of (-2000, 1000) will be imported at (-2048, 1024). +5) Specify the `import_position` of where in the world you want to import. Values are rounded to the nearest `region_size` (defaults to 256). So a location of (-2000, 1000) will be imported at (-2048, 1024). Notes: * You can import multiple times into the greater world map by specifying different positions. So you could import multiple maps as separate islands or combined regions. * It will slice and pad odd sized images into region sized chunks (default is 256x256). e.g. You could import a 4k x 2k, several 1k x 1ks, and a 5123 x 3769 and position them so they are adjacent. - * If you're importing a large file, increase the region size first. You only get 1024 regions (32x32) so you need a region size greater than image width / 32. * You can also reimport to the same location to overwrite anything there using individual maps or a complete set of height, control, and/or color. -5) Specify any desired `height_offset` or `import_scale`. The scale gets applied first. (eg. 100, -100 would scale the terrain by 100, then lower the whole terrain by 100). +6) Specify any desired `height_offset` or `import_scale`. The scale gets applied first. (eg. 100, -100 would scale the terrain by 100, then lower the whole terrain by 100). - * Note that we store full range values. If you sculpt a hill to a height of 50, that's what goes into the data file. Your heightmap values (esp w/ EXR) may be normalized to the range of 0-1. If you import and the terrain is still flat, try scaling the height up by 300-500. + * We store full range values. If you sculpt a hill to a height of 50, that's what goes into the data file. Your heightmap values (esp w/ EXR) may be normalized to the range of 0-1. If you import and the terrain is still flat, try scaling the height up by 300-500. + * See [Scaling](heightmaps.md#scale) for more details on proper scaling and offset. -6) If you have a RAW or R16 file (same thing), it should have an extension of `r16` or `raw`. You can specify the height range and dimensions next. These are not stored in the file so you must know them. I prefer to place them in the filename. +7) If you have a RAW or R16 file (same thing), it should have an extension of `r16` or `raw`. You can specify the height range and dimensions next. These are not stored in the file so you must know them. I prefer to place them in the filename. -7) Click `Run Import` and wait 10-30 seconds. Look at the console for activity or errors. If the `Terrain3D.debug_level` is set to `debug`, you'll also see progress. +8) Click `Run Import` and wait 10-30 seconds. Look at the console for activity or errors. If the `Terrain3D.debug_level` is set to `debug`, you'll also see progress. -8) When you are happy with the import, scroll down in the inspector until you see `Terrain3D / Data Directory`. Specify an empty directory and save. +9) When you are happy with the import, scroll down in the inspector until you see `Terrain3D / Data Directory`. Specify an empty directory and save. ```{image} images/io_data_directory.png :target: ../_images/io_data_directory.png ``` -You can now load this directory into Terrain3D in any of your scenes. You can also preload an existing data directory in the importer, then import more data into it and save it again. - -## Supported Import Formats - -We can import any supported image format Godot can read. These include: -* [Image formats for external files](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_images.html#supported-image-formats): `bmp`, `dds`, `exr`, `hdr`, `jpg`, `jpeg`, `png`, `tga`, `svg`, `webp` -* [Image formats stored in a Godot resource file](https://docs.godotengine.org/en/stable/classes/class_image.html#enum-image-format): `tres`, `res` -* R16 Height map aka RAW. See below. - -### Height map -* Only `exr` or `r16/raw` are recommended for heightmaps. Godot PNG only supports 8-bit per channel, so don't use it for heightmaps. It is fine for external editing of the color map which is RGBA. See [Terrain3DData](../api/class_terrain3ddata.rst) for details on data storage. -* R16: For 16-bit heightmaps read/writable by World Machine, Unity, Krita, etc. The extension should be `r16` or `raw`. Min/Max heights and image size are not stored in the file, so you must keep track of them elsewhere (such as in the name). -* `Photoshop Raw` is not R16. Use [exr](https://www.exr-io.com/) for photoshop. -* [Zylann's HTerrain](https://github.com/Zylann/godot_heightmap_plugin/) stores height data in a `res` file which we can import directly. No need to export it, but his tool also exports `exr` and `r16`. - -### Control map -* Control maps use a proprietary format. We only import our own format. Use `exr` to export or reimport only from this tool. - -### Color map -* Any regular color format is fine, `png` is recommended. The alpha channel is interpretted as a [roughness modifier](../api/class_terrain3ddata.rst#class-terrain3ddata-property-color-maps) for wetness. +You can now load this directory into Terrain3D in any of your scenes. You can also load an existing data directory in the importer, then import more data into it and save it again. ## Exporting Data @@ -80,7 +108,7 @@ We can import any supported image format Godot can read. These include: 5) Select the type of map you wish to extract: Height (32-bit floats), Color (rgba), Control (proprietary). -6) Specify the full path and file name to save. The file type is determined based upon the extension. You can enter any location on your hard drive, or preface the file name with `res://` to save it in your Godot project folder. See [export formats](#supported-export-formats) for recommendations. +6) Specify the full path and file name to save. The file type is determined based upon the extension. You can enter any location on your hard drive, or preface the file name with `res://` to save it in your Godot project folder. See [formats](#supported-formats) for recommendations. 7) Click `Run Export` and wait. 10-30s is normal. Look at your file system or the console for status. @@ -90,25 +118,4 @@ Notes: * The exporter tool does not offer region by region export, but there is an API where you can retrieve any given region, then you can use `Image` to save it externally yourself. -## Supported Export Formats - -We can export any supported image format Godot can write. These include: -* [Image save functions for external files](https://docs.godotengine.org/en/stable/classes/class_image.html#class-image-method-save-exr): `exr`, `png`, `jpg`, `webp` -* Images stored in a Godot resource file: `tres` for text, `res` for binary (with `ResourceSaver::FLAG_COMPRESS` enabled) -* R16 Height map aka RAW. See below. - -### Height map -* Use `exr` or `r16/raw` for external tools, or `res` for Godot only use. Godot PNG only supports 8-bit per channel, so it will give you blocky heightmaps. -* R16: For 16-bit heightmaps read/writable by World Machine, Unity, Krita, etc. Save with the extension `r16` or `raw`. Min/Max heights and image size are not stored in the file, so you must keep track of them elsewhere. See below to acquire the dimensions. -* `Photoshop Raw` is not raw, don't use it. Use [exr](https://www.exr-io.com/) for photoshop. - -### Control map -* Control maps use a proprietary format. We only import our own. Use `exr`. It won't give you a valid image editable in other tools or image editing apps. This is only for transferring the image to another Terrain3D data file. See [Controlmap Format](controlmap_format.md). - -### Color map -* Use `png` or `webp`, as they are lossless rgba formats that external tools can edit. Use `res` for Godot only use. The alpha channel is interpretted as a [roughness modifier](../api/class_terrain3ddata.rst#class-terrain3ddata-property-color-maps) for wetness. - - -## Exported Image Dimensions - -Upon export, the console reports the image size and minimum/maximum heights. +* Upon export, the console reports the image size and minimum/maximum heights, which is necessary for r16 heightmap exports. diff --git a/doc/docs/introduction.md b/doc/docs/introduction.md index 00368805..4df0abfb 100644 --- a/doc/docs/introduction.md +++ b/doc/docs/introduction.md @@ -22,14 +22,17 @@ The flat meshes and heightmap data are sent to the GPU, which adjusts the vertic The terrain is divided into regions, which represent both physical space, and containers for terrain data. -By default, regions are 256m x 256m, and are adjustable. This lays out a grid in the world with region borders at -256, 0, 256, 512, 768, 1024, etc. This region size also corresponds to the 256x256 pixel size of the images and textures used to store terrain data. +By default, regions are 256m x 256m, and are adjustable. This defines a grid in the world with region borders at -256, 0, 256, 512, 768, 1024, etc. This region size also corresponds to the 256x256 pixel size of the images and textures used to store terrain data. -You pay in memory and vram only for the regions you allocate. Space between the regions can be set to empty, flat, or shader generated noise (See `Terrain3D / Material / WorldBackground`). No collisions are generated outside of regions. +You pay in memory and VRAM only for the regions you allocate. Space between the regions can be set to empty, flat, or shader generated noise (See `Terrain3D / Material / WorldBackground`). No collisions are generated outside of regions. + +There is currently a limit of 1024 regions or 32 x 32. So the maximum dimensions of the your world are `32 * region_size`. The maximum being 32 * 2048 or 65,536m per side. Region files are stored in the data directory as individual files, with their location coordinates in the filename. e.g. terrain3d_01-02.res, which represents region (+01, -02). The region grid is visible if `View Gizmos` is enabled in the Godot `Perspective` menu. Or if `Terrain3D / Regions / Show Grid` is enabled. + ## Region Location Region locations are the grid coordinates that regions fit into. Represented as a Vector2i, eg (-1, 0), this is the primary key used for identifying regions in the API. @@ -38,6 +41,7 @@ Converting a global position to a region location is calculated by `floor(global Set `Terrain3D / Regions / Label Distance` to 1024-4096 to see region coordinates in the viewport. + ## Vertex Painting This system is a vertex painter, not a pixel painter. In order to make a high performance terrain, we are spreading out say a 1024 x 1024 map over 1024m^2. Each square meter is influenced by only 4 pixels in the corners. diff --git a/doc/docs/misc.md b/doc/docs/misc.md index 7b9c65c5..0b7ea34c 100644 --- a/doc/docs/misc.md +++ b/doc/docs/misc.md @@ -19,12 +19,3 @@ To use it: * Find Terrain3DObjects * Add nodes as children of this node - - -## Minimal Shader - -You'll find a shader that provides just the minimum needed to allow the terrain to work in `extras/minimum.gdshader`. - -It includes no texturing. - -Load this shader into the override shader slot and enable it. Customize as you see fit. diff --git a/doc/docs/tips.md b/doc/docs/tips.md index 6ce7bb88..c3d20c77 100644 --- a/doc/docs/tips.md +++ b/doc/docs/tips.md @@ -20,6 +20,13 @@ You can determine if a given location is within a region by using `Terrain3DData ## Shaders +### Minimal Shader + +This terrain is driven by the GPU, and controlled by our shader. We provide a minimal shader that has only the code needed to shape the terrain mesh without any texturing. You can find it in `extras/minimum.gdshader`. + +Load this shader into the override shader slot and enable it. It includes no texturing so you can create your own. + + ### Day/Night cycles & light under the terrain The terrain shader is set to `cull_back`, meaning back faces are neither rendered, nor do they block light. If you have a day/night cycle and the sun sets below the horizon, it will shine through the terrain. Enable the shader override and change the second line to `cull_disabled` and the horizon will block sunlight. This does cost performance. diff --git a/doc/index.rst b/doc/index.rst index a660d75e..2d6e650f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -96,6 +96,7 @@ Geometry clipmap mesh code created by `Mike J. Savage void: r16_size = Vector2i(1024, 1024) material = null assets = null + reset_terrain(true) func reset_terrain(p_value) -> void: data_directory = "" + for region:Terrain3DRegion in data.get_regions_active(): + data.remove_region(region, false) + data.force_update_maps() func update_heights(p_value) -> void: