====== atCalc_AM_MaskOverlay ======
===== Plugin information ===
^ Author: | [[user>Aaron]] |
^ Description | Applies a selected land type to the attributes map using a mask map. |
^ Menu option | '//Operations->Attributes map->Mask overlay//' |
^ Download link | Included with L3DT 12.07 installer; no separate download. |
^ Source code | //Not available.// |
^ Last update | 11 July 2015. |
^ Dependencies | L3DT 12.07 or later, L3DTio_BigBitmap, L3DTio_FI, ZeoScript. |
===== Using atCalc_AM_MaskOverlay =====
==== Menu option ====
This plugin implements the '//Operations->Attributes map->Mask overlay//' menu option in L3DT, as described in the [[bundydocs>l3dt:userguide:ops:am:MaskOverlay|user guide]].
==== Scripting ====
This plugin exports two scripting functions for use in ZeoScript; ''calc.AM.MaskOverlay'', and ''UI.atCalc_AM_MaskOverlay.MaskOverlayUI'':
=== calc.AM.MaskOverlay ===
The ''calc.AM.MaskOverlay'' extension function implements the underlying calculation for the '//Operations->Attributes map->Mask overlay//' menu option, which applies a climate/land type to a specific area of the attributes map, as selected by a mask map.
The function prototype is:
bool MaskOverlay(string MaskMapName, bool IsFileName, string CliName, string TypeName, float Threshold, uint Flags, hvar hOptions);
The return value is a boolean of true if the calculation succeeded without errors, and false otherwise.
The function arguments are listed below:
^ Argument ^ Data type ^ Description ^
| //MaskMapName// | string | The name of the mask map, which depending on the value of the //IsFileName// argument, represents either a full path to a map file on disk (PNG or BMP format), or the name of an existing map layer in the current project. |
| //IsFileName// | bool | A flag that indicated whether the //MaskMapName// argument is a full path to a map file on disk. If ''false'', //MaskMapName// refers to the name of an existing map layer in the current project. |
| //CliName// | string | The name of the climate to be used for the overlay. |
| //TypeName// | string | The name of the land type (within the climate referred to by //CliName//) that is to be used for the overlay. If null, the land type is auto-calculated for each pixel using the same calculation as for generating the attributes map. |
| //Threshold// | float | The greyscale level in the mask image above which the overlay will be applied. Values are normalised from 0->1. |
| //Flags// | uint | A bitwise combination of flags to modify the behavior of the calculation. See //Values of 'Flags'// section below for supported values. |
| //hOptions// | hvar | Reserved for later use. Must be NULL. |
== Values of 'Flags' ==
Thew following values for the //Flags// arguments are supported:
^ Value ^ Description ^
| 0x1 | Display an in-line progress window, to be used if the caller is //not// running inside the calculation manager's thread. Mutually exclusive with 0x2. |
| 0x2 | Display a threaded progress window, to be used if the caller is running inside the calculation manager's thread. Mutually exclusive with 0x1. |
=== UI.atCalc_AM_MaskOverlay.MaskOverlayUI ===
The ''UI.atCalc_AM_MaskOverlay.MaskOverlayUI'' extension function will open the 'Attributes map mask overlay' window ([[bundydocs>l3dt:userguide:ops:am:maskoverlay|see user guide]]).
The function takes no arguments, and returns a boolean value of true if the user clicked OK in the window and no errors occurred, and false otherwise. The function prototype is given below:
bool UI.atCalc_AM_MaskOverlay.MaskOverlayUI(void);
==== ZeoGraph ====
The filter function for this plugin in [[plugins:calc:ZeoGraph]] is ''AttributesMap.MaskOverlay'', and is described on the [[plugins:calc:zeograph:filters:am_MaskOverlay|filter reference page]].
===== Changes =====
2012/07/12 --- Released v12.07.