====== atRainMaker ====== ===== Plugin information === ^ Author | [[user>Aaron]] | ^ Description | An experimental plugin for water flow modelling. | ^ Download link | [[http://www.bundysoft.com/L3DT/downloads/plugins/bin/atRainMaker-bin.zip|atRainMaker-bin.zip]] [107kB] | ^ Last updated | 6th of August 2012. | ^ DLL version | 12.8.0.0 | ^ Dependencies | L3DT Pro v11.11 or later | ===== Using atRainMaker ===== Before we start I should point out that this calculation is rather intensive (read: slow), so as your first try with this plugin I recommend something unambitious, like a 512x512 map. Anyway, on to the calculation. The plugin splits the calculation into three parts: - Calculation of the rain flow maps. - Filtering/processing of the rain flow maps. - Overlaying the flow maps onto the water map. This plugin has no user-interface, so each stage requires us to enter some simple scripts, which I've listed below. ==== Quick example script ==== Download {{:plugins:calc:atrainmaker:rainplugintest.zs|this script file}}, and put it in your L3DT script folder at: ^ Win 7 / Vista | C:\Users\[your username]\L3DT\Resources\[version]\Scripts | ^ Win XP / 2000 | C:\Documents and Settings\[your username]\L3DT\resources\[version]\Scripts | Then: * Start L3DT * Load your map project * Select the '//Scripts->More scripts...//' menu item * Select the 'RainPluginTest' item from the list. This will generate the rain depth mask using some default settings, which you can change by editing the script file ('//Scripts->Edit script//'). ==== Calculating rain flow maps ==== Select the '//Scripts->New script//' menu option, and enter the following code: calc.WM.rain 1 100 1 1 1 The function arguments for this script call are: ^ Name ^ Type ^ Default value ^ Description ^ | pHF | hvar |  "HF"> | The heightfield handle. Using the ''GetMap'' function to retrieve the project's heightfield. | | pWM | hvar |  "WM>" | The water map handle. Using the ''GetMap'' function to retrieve the project's water map. | | SampleRate | int | 1 | Normally this is 1, but if you want to speed-up the calculation (at the expense of some detail), set this to 2 or 4. | | nCycles | int | 100 | The number of iterations of the calculation. Normally this should be several hundred.| | WaterLevel | float | 1 | The initial water level, which normally should be about 1 (units of metres, of course). __Must be positive__.| | EvapRate | float | 1 | The evaporation rate. Normally this should be ~ the same as the initial water level. __Must be positive__. | | CalcFlags | uint | 1 | Described below. | The //CalcFlags// argument is a bitfield combination, the values of which have the following meanings: ^ Value ^ Meaning ^ | 1 | Calculate the average depth map. | | 2 | Calculate the flow map. | | 3 | = 1+2 | | 4 | Calculate the maximum depth map. | | 5 | = 1+4 | | 6 | = 2+4 | | 7 | = 1+2+4 | | 8+ | undefined | After you click OK in the script dialog, the plugin will start its calculation. Once the calculation is complete, you will now have a new maps in your project called '//Rain-avgdepth//'. You can view this using the '//View->Show map//' menu option, and you should see something like this: {{ :plugins:calc:atrainmaker:avgdepth.jpg |:plugins:calc:atrainmaker:avgdepth.jpg}} ==== Filtering the flow maps ==== Before we can apply the rain depth map to the water map, we must first do some processing. There are in fact a large number of different scaling and manipulation options you can apply, but in this case I'm going to do one simple thing: subtract the initial flood depth (1m). To do this, I enter the following script: calc.HF.ShiftMap -1 true ==== Applying the flow maps to the water map ==== The final step is to bake the rain depth map onto the water map. To do this, use the following script: calc.WM.ApplyOverlayMax true The map is now ready to be viewed in the main window, or in Sapphire. If you don't like the result, you can undo using the '//Edit->Undo//' menu option. ==== Putting it all together ==== If you want to do all that processing back-to-back and automagically, select '//Scripts->New script//' in the menu and enter the following script: calc.WM.rain 1 100 1 1 1 calc.HF.ShiftMap -1 true calc.WM.ApplyOverlayMax true ===== Import / Export ===== ==== Export ==== To export the rain depth map, select the '//File->Export->Export map...//' menu item, select the 'Rain-avgdepth' map, and export the map in whichever format you like. ==== Import ==== To re-import the rain depth map, use the '//File->Import->New map layer//' menu item. ===== To do list ===== There are many things still to do, but the most obvious one are: * Integration with L3DT's internal calculation manager. * Split the calculation into tiles and run it through the multithreaded tile calc manager (as used for normals/light/texture map calcs). * Calculate sediment removal and accumulation maps (use for erosion). ===== Change log ===== 2012/08/06 --- Added parameter validation, better logging, and proper support for virtual mosaic maps. 2012/07/30 --- Updated example scripts for current release version of ZeoScript language. 2012/01/11 --- Recompiled for API version 11.09. 2009/08/11 --- Removed code for rendering in Sapphire, added 'cancel' button in progress box, updated backup behaviour, and updated scripts. 2007/08/02 --- Uploaded.