VR Calculator Alpha

Overview

The VR Calculator Alpha tool computes Variable Retention (VR) influence statistics for forestry coupes. It determines what percentage of a harvested (felled) area falls within the influence zone of retained trees, based on tree height and one-tree-length distance calculations.

The tool runs as an asynchronous geoprocessing (GP) job on the ArcGIS Server, allowing you to continue working while the calculation processes.

Alpha Status

This tool is in alpha and may change in future releases. Results should be verified against field measurements before use in formal reporting.

LiDAR Coverage

This tool uses Virtual Tas LiDAR-derived height data (DHM Raster) by default. If your coupe is outside LiDAR coverage, switch the Height Source to "User Height" and enter a tree height in metres.

Key Features

• Two Calculation Modes: Planned mode (custom harvest and aggregate geometry) and Final mode (uses existing server-side coupe boundaries)
• Flexible Height Sources: Use LiDAR-derived Digital Height Model (DHM) raster data or specify a manual tree height
• Three Geometry Inputs: Define harvest, aggregates, and discount areas by drawing polygons or selecting from existing map layers
• Colour-Coded Geometry: Each geometry type is displayed in a distinct colour for easy identification on the map
• Contextual Guidance: Hint messages appear when draw or select tools are active, guiding you through each step
• Asynchronous Processing: Submit jobs and monitor progress with real-time status updates
• Job Message Log: View full server processing messages in a draggable dialog
• Influence Visualisation: Results are automatically added to the map as a yellow influence layer with padded zoom
• Comprehensive Statistics: Detailed breakdown of coupe area, felled area, influence percentage, and LiDAR coverage

How to Use the VR Calculator

Accessing the Tool

1. Navigate to the Report Tools panel in the right sidebar
2. Select VR Calculator Alpha from the report tools dropdown
3. The tool panel opens showing an information notice about LiDAR coverage, form inputs, geometry tools, and action buttons

Step 1: Enter Coupe Identifier

Enter the coupe code in the Coupe field. The code must follow the standard format: 2 letters + 3 digits + 1 letter (e.g., AR022D, SR025C, TN065A). The input is automatically converted to uppercase.

The coupe code is used to look up the coupe boundary from the server-side database for area calculations.

Step 2: Select Calculation Mode

Choose a calculation mode from the Mode dropdown:

Mode	Description
Planned (default)	Uses your drawn/selected harvest and aggregates geometry for the calculation. Use this when planning a harvest operation.
Final	Uses existing coupe boundaries stored on the server. Harvest and aggregates geometry inputs are disabled. Use this after harvesting is complete.

INFO

When you switch to Final mode, any existing harvest and aggregates geometry is automatically cleared from the map, and the draw/select/clear buttons for those fields are disabled.

Step 3: Choose Height Source

Select how tree heights are determined:

Height Source	Description
DHM Raster (WCS) (default)	Uses the LiDAR-derived Digital Height Model raster from the GeoServer Web Coverage Service. Provides the most accurate, spatially-varying tree heights.
User Height	Specify a uniform tree height in metres. A numeric input field appears when this option is selected. Use this when LiDAR data is unavailable or you want to model a specific height scenario.

Step 4: Define Geometry Areas

The tool supports three types of optional geometry input. Each is colour-coded on the map:

Geometry	Colour	Purpose
Harvest	Pink	Defines the planned harvest boundary. Disabled in Final mode.
Aggregates	Blue	Defines aggregate retention areas within the coupe. Disabled in Final mode.
Discount	Orange	Defines areas to exclude from influence calculations (e.g., roads, landings). Available in both modes.

Each geometry field has three buttons:

• Draw (polygon icon) — Click points on the map to draw a custom polygon. Double-click to complete. Click the button again while drawing to cancel.
• Select (cursor icon) — Click on a polygon from the selected map layer to use its boundary. Requires a layer to be chosen from the Select from Layer dropdown.
• Clear (trash icon) — Remove the current geometry for that field.

When a draw or select tool is active, a contextual hint appears below the geometry section to guide you:

• Drawing: "Click to add vertices on the map. Double-click to finish the polygon."
• Selecting: "Click on a polygon in the map to select it."

A status indicator beside each geometry label shows:

• Set (green) — Geometry has been defined
• Not set (optional) — No geometry defined (all geometry inputs are optional)
• Disabled in final mode — Field is not available in Final mode

Selecting a Source Layer

The Select from Layer dropdown lists all visible polygon layers on the map. Click the dropdown to refresh the layer list. This layer is used as the source when you click the Select button for any geometry field.

The tool supports:

• Feature Layers — Direct polygon selection via hit-test or spatial query
• Map Image Layers — Polygon selection via identify operation on visible sublayers

Step 5: Submit the Calculation

1. Verify your inputs:
   • Coupe code is entered in the correct format (e.g., AR022D)
   • Mode is selected
   • Height source is configured
   • Geometry areas are defined as needed
2. Click the Submit button (play icon)
3. The button shows a loading indicator while the job processes
4. Real-time status messages appear below the action buttons

Monitoring Job Progress

While the job is running:

• A progress indicator shows the current status with user-friendly labels (e.g., "Submitted", "Processing")
• The latest server message is displayed inline
• A message count badge appears — click it to open the full Job Messages dialog
• A Cancel button appears to abort the job if needed

Job Messages Dialog

Click the message count badge to open the Job Messages dialog:

• Draggable and resizable — position it anywhere on screen
• Non-modal — you can continue interacting with the map while viewing messages
• Messages are displayed in a numbered, scrollable list with monospace font
• Error messages are highlighted in red for easy identification
• Auto-scrolls to the latest message as they arrive during processing
• The dialog heading updates to reflect the job state (Processing, Completed, or Failed)
• Footer shows the current status and total message count

The dialog can also be opened after the job completes to review the full processing log.

Understanding Your Results

When the job completes successfully, two things happen:

1. Influence Layer on Map

A yellow influence layer is added to the map showing the spatial extent of the one-tree-length influence zone. The map automatically zooms to the result extent with comfortable padding around the boundaries. The layer appears in the Layer Panel as "VR Influence - {coupe code}" and can be toggled on/off.

2. Statistics Table

A results table displays the following metrics:

Statistic	Description
Coupe	The coupe identifier used for the calculation
Coupe Area (ha)	Total coupe boundary area in hectares
Aggregate Retention (ha)	Area of aggregate retention within the coupe
Felled Area (ha)	Net felled area (coupe minus aggregates)
1-Tree Influence Area (ha)	Area within one tree length of retained trees
Influence (%)	Percentage of felled area under tree influence — the key VR metric
Without Influence (ha)	Felled area not under tree influence
Without Influence (%)	Percentage of felled area without influence
Height Source	Which height data was used (DHM Raster or User Height)
User Height (m)	The manual height value if User Height was selected
LiDAR Coverage (%)	Percentage of the area covered by LiDAR height data

A success banner at the top highlights the key result: Influence percentage of felled area.

Resetting the Tool

Click the Reset button (reset icon) to:

• Clear all geometry from the map
• Reset all form inputs to defaults (Planned mode, DHM Raster height source)
• Remove the influence result layer
• Clear job status and results

Worked Example

Planned Mode Calculation

1. Enter coupe code: TN065A
2. Leave mode as Planned
3. Leave height source as DHM Raster (WCS)
4. Click the Draw button for Harvest — a hint appears: "Click to add vertices..."
5. Draw a harvest polygon around the planned harvest area
6. Optionally draw an aggregates polygon for retention clumps
7. Click Submit
8. Monitor progress via the inline status or open the Job Messages dialog for full details
9. Wait for the job to complete (~30 seconds to several minutes depending on area size)
10. Review the influence percentage in the results table
11. Inspect the yellow influence zone on the map (automatically zoomed with padding)

Final Mode Calculation

1. Enter coupe code: TN065A
2. Switch mode to Final
3. Note that harvest and aggregates buttons are disabled
4. Optionally draw a discount polygon for roads or landings
5. Click Submit
6. The server uses the stored coupe boundary for calculations

Troubleshooting

Issue	Solution
Submit button is disabled	Wait for a running job to complete, or check that you are not in a loading state
"Coupe Required" error	Enter a coupe code in the correct format: 2 letters + 3 digits + 1 letter (e.g., AR022D)
Job fails with an error	Check the error message in the Job Messages dialog — common causes include invalid coupe code, server connectivity issues, or missing data for the specified area
Harvest/aggregates buttons are disabled	Switch from Final mode to Planned mode to enable these geometry inputs
No layers in the Select from Layer dropdown	Ensure at least one polygon layer is visible on the map. Click the dropdown to refresh
Select from layer not responding	Verify you have chosen a layer from the dropdown first
Influence layer not visible	Check the Layer Panel — the layer may be toggled off. It appears as "VR Influence - {coupe}"
Results seem incorrect	Verify that the correct geometry was drawn and the right height source was selected. Check LiDAR Coverage % — low values may indicate insufficient height data
Job takes a long time	Processing time depends on coupe size and height source. DHM Raster calculations for large areas may take several minutes. Open the Job Messages dialog to monitor progress
Cannot cancel a job	The Cancel button only appears while a job is actively running
User Height input not visible	Switch the Height Source dropdown to "User Height" — the input field appears when this option is selected

Frequently Asked Questions

Q: What is Variable Retention (VR)? A: Variable Retention is a silvicultural system where trees are retained across a harvest area to maintain forest structure, habitat, and biodiversity values. The VR influence metric measures how much of the felled area falls within one tree length of retained trees.

Q: What does "1-Tree Influence" mean? A: It refers to the zone within one tree height distance from retained trees or forest edges. Trees within this zone provide ecological benefits such as seed rain, wind protection, and habitat connectivity.

Q: When should I use Planned vs Final mode? A: Use Planned mode during harvest planning to test different harvest and retention configurations. Use Final mode after harvesting is complete to calculate the actual VR result using the surveyed coupe boundary stored on the server.

Q: Why is the DHM Raster height source preferred? A: The DHM Raster uses LiDAR-derived tree height data that varies spatially across the coupe, providing the most accurate influence calculations. User Height applies a uniform height everywhere, which may over- or under-estimate influence in areas with variable canopy height.

Q: What happens if LiDAR coverage is low? A: The LiDAR Coverage percentage in the results indicates how much of the analysis area has DHM height data. In areas without coverage, the tool may fall back to default assumptions. Low coverage values suggest switching to User Height with a known average tree height for more reliable results.

Q: Can I save or export the results? A: The influence layer is added to the map as a graphics layer and can be viewed in the Layer Panel. Currently, results are not directly exportable — take a screenshot or record the statistics manually for reporting.

Q: Are all three geometry inputs required? A: No. All geometry inputs (harvest, aggregates, discount) are optional. The server performs calculations based on whichever geometry is provided. In Final mode, harvest and aggregates are automatically ignored.

Q: Why does my coupe code get converted to uppercase? A: Coupe codes are standardised in uppercase format to match the server-side database records.

Q: What format must the coupe code be in? A: The coupe code must be 2 uppercase letters followed by 3 digits and 1 uppercase letter (e.g., AR022D, SR025C, TN065A).

Q: How do I view all the server messages from a job? A: Click the message count badge next to the status line to open the Job Messages dialog. This shows all messages in a scrollable list. The dialog can be opened during or after job completion.