# AeroField User Manual **Rhino 8 and Grasshopper comparative exterior wind-flow preview** This manual explains how to install, operate, interpret, and export results from AeroField. It begins with a one-component study and progresses to advanced control of resolution, domain size, flow paths, scalar fields, viewport graphics, baking, and movies. --- ## Contents 1. [What AeroField Does](#1-what-aerofield-does) 2. [Installation](#2-installation) 3. [Ten-Minute Quick Start](#3-ten-minute-quick-start) 4. [The Three AeroField Components](#4-the-three-aerofield-components) 5. [AeroField Study Reference](#5-aerofield-study-reference) 6. [The Five Visualization Methods](#6-the-five-visualization-methods) 7. [AeroField Advanced Settings Reference](#7-aerofield-advanced-settings-reference) 8. [Flow Physics, Colors, and Scalar Fields](#8-flow-physics-colors-and-scalar-fields) 9. [Calculation and Display Updates](#9-calculation-and-display-updates) 10. [Baking to Rhino](#10-baking-to-rhino) 11. [Animation Export](#11-animation-export) 12. [Recommended Workflows](#12-recommended-workflows) 13. [Warnings and Troubleshooting](#13-warnings-and-troubleshooting) 14. [Interpretation and Limitations](#14-interpretation-and-limitations) 15. [Quick Reference](#15-quick-reference) --- ## 1. What AeroField Does AeroField is a Grasshopper plugin for early architectural wind studies. It calculates a three-dimensional exterior velocity field around one or more building masses and turns that field into clear Rhino viewport graphics. Use AeroField to: - compare massing alternatives under the same wind; - inspect how air approaches, passes around, rises over, and trails behind buildings; - identify accelerated regions and sheltered regions; - inspect pedestrian-height conditions on a horizontal plane; - inspect a vertical or horizontal section through the field; - compare relative exposure on building surfaces; - bake flow graphics into Rhino; - create a short presentation movie from the current Rhino view. AeroField is a comparative design tool. It is not a replacement for code-compliance analysis, a wind tunnel, structural wind-load analysis, or a validated engineering simulation. Use specialist analysis when decisions involve public safety, facade loads, comfort certification, or regulatory approval. ### 1.1 What AeroField calculates The primary result is a three-dimensional velocity field. From that field, AeroField can derive and display: - speed in meters per second; - speed-up ratio relative to the local incoming wind; - a pressure proxy derived from velocity; - vorticity magnitude; - Q criterion; - vertical velocity; - X, Y, and Z velocity components; - divergence; - flow-disturbance and speed-deficit proxies; - three-dimensional flow paths; - a pedestrian-height analysis surface; - relative building-surface exposure. The pressure proxy is a comparative visualization, not a pressure coefficient or facade design load. AeroField does not calculate temperature, buoyancy, indoor airflow, or natural ventilation. Before reading any field physically, see [Section 8, Flow Physics, Colors, and Scalar Fields](#8-flow-physics-colors-and-scalar-fields), which defines every displayed quantity and its interpretation limits. ### 1.2 Coordinate and wind convention `Wind From degrees` uses the meteorological convention: | Value | Wind arrives from | Travel direction | |---:|---|---| | 0 | North | Toward south | | 90 | East | Toward west | | 180 | South | Toward north | | 270 | West | Toward east | The model uses Rhino world Z as vertical. Buildings should stand upright above a common ground elevation. --- ## 2. Installation ### 2.1 Requirements - Rhino 8.30 or newer for macOS or Windows; the current Rhino 8 service release is recommended - Grasshopper, included with Rhino 8 - `AeroField.gha` - `AeroField.Core.dll` - `ffmpeg` for encoded movie files Keep the `.gha` and `.dll` together in the same plugin folder. ### 2.2 Install from a ZIP package 1. Close Rhino. 2. Extract the AeroField package. 3. Open Rhino's Grasshopper Libraries folder. 4. Copy `AeroField.gha` and `AeroField.Core.dll` into that folder. 5. On Windows, right-click each downloaded file, choose **Properties**, and select **Unblock** when that option is present. 6. Start Rhino 8 and open Grasshopper. 7. Confirm that the **AeroField** tab contains three public components: **AeroField Study**, **AeroField Advanced Settings**, and **AeroField Animation Export**. ### 2.3 Avoid duplicate installations Grasshopper must find only one AeroField assembly. If a conflict dialog lists two identical `.gha` files, retain the intended installation and remove the duplicate. Common duplicate locations include a manual Grasshopper Libraries folder and Rhino's package-manager folder. Restart Rhino completely after changing plugin files. ### 2.4 Model units AeroField interprets Rhino document units physically and converts lengths to meters for the calculation. Before beginning: AeroField accepts connected geometry at the Rhino document's current scale and begins without requiring a separate dimension check. The interpreted physical dimensions remain available in Summary and Diagnostics when they are useful for analysis. --- ## 3. Ten-Minute Quick Start ### 3.1 Prepare a first building 1. Open Rhino 8. 2. Confirm the document units. 3. Draw a closed box representing a building. 4. Place its base at the intended ground elevation. 5. Open Grasshopper. 6. Add a **Geometry** parameter and reference the Rhino box. 7. Add **AeroField Study** from the AeroField tab. 8. Connect the Geometry parameter to `Geometry`. That is the complete minimum wiring: ```text Rhino building geometry | v Grasshopper Geometry parameter | v AeroField Study.Geometry ``` The Study calculates automatically. There is no Run input because Grasshopper already updates the component when an input changes. ### 3.2 Set the wind The default values are: - wind speed: `10 m/s`; - wind from: `0 degrees`, meaning from north; - analysis height: `1.5 m` above ground; - quality: `Standard` when Quality is unconnected. Connect Number Sliders or Panels when different values are required. Leave an input unconnected to use its displayed default. ### 3.3 Read the first view Visualization button **1** is selected by default. It displays detailed three-dimensional streamlines colored by velocity. With the normal Standard field, incoming and bypass paths can bend or meander modestly as they follow the calculated velocity field, while the wake shows the stronger turning and recirculation produced downstream of the buildings. Every ordinary approach path begins at the calculated inlet boundary and remains one continuous trace through the site and downstream field. A streamline is a directional curve through the stored velocity field, not a measured smoke trail or a flow-rate indicator; see [What streamlines do, and do not, show](#84-what-streamlines-do-and-do-not-show). Orbit the Rhino camera. A valid three-dimensional result should show paths moving around both sides of the building and over its roof. A symmetric cube in a centered, straight wind should have no persistent left-right bias. ### 3.4 Add status panels Connect these optional outputs to Grasshopper Panels: ```text AeroField Study.Summary -> Panel AeroField Study.Diagnostics -> Panel ``` `Summary` is the main user-facing status. `Diagnostics` provides additional detail for troubleshooting. ### 3.5 Change the view without recalculating Click buttons **1** through **5** along the bottom of the Study component. A visualization-method change reuses the existing field and updates only the display. This should be much faster than the initial calculation. --- ## 4. The Three AeroField Components ### 4.1 AeroField Study This is the main component. It accepts building geometry and ordinary study inputs, performs the calculation automatically, and draws the selected visualization directly in Rhino. The five numbered buttons select the visualization method. **BAKE VIEW TO RHINO** creates persistent Rhino geometry from the currently displayed result. ### 4.2 AeroField Advanced Settings This optional component contains controls that are useful after the basic workflow is understood. It groups resolution, field size, incoming-wind profile, streamline composition, scalar fields, and live viewport graphics. You do not need this component for a normal study. Connect its `Advanced Settings` output to the Study's `Advanced Settings` input only when you want to override a quality preset. Unconnected advanced inputs inherit the selected Base Quality preset. This lets you change one advanced value without manually recreating every other setting. ![AeroField Advanced Settings connected to Study](figures/aerofield-advanced-settings-connected.png) *An Advanced Settings workflow. Connect the component's `Advanced Settings` output to the Study component's `Advanced Settings` input. The Number Slider shown here is connected to `Ground Elevation m` as an illustrative override; other settings remain optional.* ### 4.3 AeroField Animation Export This component creates a short movie from the current Study and Rhino camera. It has one input and one output: ```text AeroField Study.Study -> AeroField Animation Export.Study ``` Frames are prepared automatically. Use **EXPORT MOVIE** for an automatic filename and location, or **SAVE AS...** to choose the filename, folder, and an available format. `Movie Path` reports the last successful file. ![AeroField Study connected to Animation Export](figures/aerofield-animation-export.png) *A complete movie-export setup. Connect the Study output to the Animation Export `Study` input. When the footer reports that frames are ready, use **EXPORT MOVIE** or **SAVE AS...**.* --- ## 5. AeroField Study Reference ### 5.1 Inputs | Input | Default | Purpose | |---|---:|---| | Geometry | Required | Closed building masses or meshes | | Wind Speed m/s | 10 | Incoming reference speed in meters per second | | Wind From degrees | 0 | Meteorological incoming direction | | Analysis Height m | 1.5 | Height above ground for the horizontal analysis plane | | Quality | Standard | Leave unconnected for the normal developed field, or connect Preview, Standard, or Detailed | | Advanced Settings | Empty | Optional settings object from AeroField Advanced Settings | ### 5.2 Building geometry Use clean, closed masses whenever possible. Multiple buildings may be supplied as a list. Avoid accidental remote geometry, duplicate shells, tiny detached objects, and details that are much smaller than the intended field resolution. Closed Breps and closed meshes produce the clearest occupancy representation. AeroField can conservatively approximate problematic open geometry and reports that choice in Diagnostics. For a multi-building site, leave `Quality` unconnected for Standard. AeroField treats the connected masses as one site, preserves every occupied building, and selects the finest practical site grid within the configured limits. Summary reports the achieved resolution and any bounded site adaptation. Use that achieved resolution when comparing wake width, recirculation, or differences between individual buildings. Connect Preview only for a deliberately faster overall-flow check; its smoother, shorter field development can suppress small wake structures. ### 5.3 Wind Speed m/s This is the incoming reference wind speed. Valid values are greater than 0 and no more than 100 m/s. For comparisons, keep the speed constant while changing only the building design. ### 5.4 Wind From degrees Angles are normalized to the range from 0 through 360 degrees. The value describes where the wind comes from, not where it goes. ### 5.5 Analysis Height m This is a height above ground, not a world-Z coordinate. The default `1.5 m` is a common pedestrian-level inspection height. Changing this input samples a different horizontal plane from the existing three-dimensional field and does not repeat the main calculation. If the requested height lies outside the calculated field, AeroField omits the plane, keeps valid three-dimensional paths visible, and reports a warning. ### 5.6 Quality Accepted values are: - `Preview`: fastest exploratory setting and a smoother mean-flow check; - `Standard`: automatic normal setting with developed approach, bypass, and wake structure; - `Detailed`: higher target resolution and a longer calculation. Leave Quality unconnected for Standard in ordinary work. Use Preview when quick confirmation of geometry, wind direction, or broad deflection is more important than detailed path character. Use Detailed selectively after the study setup is stable. Standard and Detailed include a small, reproducible, balanced variation in the incoming cross-flow while the field develops. The default Standard magnitude is 3 percent of the incoming speed at the same height. The lateral and vertical contributions are balanced across the inlet, so they do not impose a net sideways or upward wind. This supplies physically coherent three-dimensional variation without adding decorative wiggles to the displayed curves. The variation belongs to the calculated velocity field. Individual paths can therefore differ slightly even in a symmetric study, while the path family and scalar field should retain no persistent left-right bias. Preview omits this evolving cross-flow variation and therefore normally appears smoother. When a study needs a longer physical approach, increase **Upwind Domain H** in Advanced Settings and rerun the field. ### 5.7 Advanced Settings Leave this input empty for ordinary use. When a connected Advanced Settings object is present, its Base Quality and overrides are authoritative. ### 5.8 Outputs | Output | Type | Purpose | |---|---|---| | Summary | Text | Main calculation status, field dimensions, timing, and interpretation notes | | Flow Paths | Curves | Bakeable three-dimensional paths | | Analysis Plane | Mesh | The current horizontal analysis surface when valid | | Study | AeroField data | Connection to Animation Export | | Diagnostics | Text list | Detailed preparation, calculation, caching, and display information | The Study component previews its result directly. Do not connect Flow Paths or Analysis Plane merely to make them visible. A downstream preview-enabled parameter may draw a second copy in Grasshopper's default color. ### 5.9 On-component controls | Control | Action | |---|---| | 1 | Detailed 3D Streamlines | | 2 | Wake and Vortex | | 3 | Pedestrian Wind Map | | 4 | Flow Sections | | 5 | Surface Exposure | | BAKE VIEW TO RHINO | Creates persistent Rhino geometry for the active view | Right-clicking the Study also provides named visualization choices, cancellation of active work, and baking. --- ## 6. The Five Visualization Methods ### 6.1 Method 1: Detailed 3D Streamlines Use Method 1 to understand the overall three-dimensional route of the wind. It emphasizes a dense, readable family of paths around and over the buildings. For the physical meaning and limits of streamlines, see [What streamlines do, and do not, show](#84-what-streamlines-do-and-do-not-show). For a multi-building field, Method 1 evaluates downstream path candidates relative to the undisturbed incoming speed at the same height. It then reserves a local wake bundle for every building whose calculated downstream region contains meaningful flow disturbance. Those paths are distributed across the local wake's width and height before the remaining global path slots are filled. This avoids allowing one energetic building to consume nearly every wake path or allowing a broad wake to appear as one narrow core line. This is a display-coverage guarantee, not synthetic turbulence. AeroField does not draw decorative eddies when the calculated field contains no meaningful speed deficit, turning, or rotational activity. If one building has a smooth or narrow wake, inspect Summary and Diagnostics and verify the achieved cells across. If you deliberately selected Preview, return to Standard before interpreting that difference as physical. Standard is a developed snapshot rather than a perfectly smooth mean-flow picture. Its balanced incoming variation can give calculated approach, roof-bypass, and side-bypass paths modest curvature or meander before and around the buildings. The result should look coherent rather than random: most remote paths still follow the mean wind, stronger bends should be associated with the site or evolving flow structures, and a centered path family should not drift systematically to one side. Every ordinary Method 1 path is one continuous integration through the calculated field: it begins at the solved inlet boundary and continues to its downstream termination. AeroField does not append far-field segments, join separate path pieces, or introduce an artificial upstream seed plane. Additional wake-focused paths may begin inside the calculated wake so that recirculation and local rotational structures remain readable. The calculated path samples remain the source geometry. For a clean viewport, Method 1 constructs a piecewise tangent-continuous presentation curve between those samples. Each piece has bounded handles and is checked locally against occupied buildings and against the source path. If a smooth piece could enter a solid or depart too far from the checked path, AeroField conservatively retains that source segment. This local approach removes polygonal corners without allowing a failure in one region to make the entire streamline angular, and without changing the stored field or manufacturing wake motion. Path colors represent local velocity magnitude `U` in meters per second. Every visible span is associated with one exact physical source segment and receives `U` by interpolation only between that segment's neighboring velocity samples. Every path uses the same displayed legend range, so equal `U` values receive the same color and colors are not assigned randomly by path. The curve is drawn without a dark outline, so a zoomed path should look like a solid colored stroke rather than a dotted or grainy line. The default robust global range ignores isolated extremes so useful variation remains visible across the path family. When **Color Legends** is enabled, the vertical legend at the right of the Rhino viewport is headed `U (m/s)`. Its blue-through-cyan, green, yellow, orange, and red colors are exactly the colors used for the Method 1 path spans, and its numbered ticks give the corresponding speed in meters per second. Read a path by matching its color to that bar; the sideways `U (m/s)` text is the unit label, not another scale. The legend is a viewport aid and is intentionally omitted from exported movie frames. #### Reading Method 1 from three viewpoints The same field can look very different from each Rhino camera direction. The following study contains two building assemblies: an arch made from three rectangular masses (two vertical supports and one horizontal lintel), plus a nearby truncated pyramid. It uses 150 displayed paths and a `Detailed Line Width px` setting of `1.5` for clearer screen reading. The thicker lines are a presentation setting only; they do not change the calculated field. ![Method 1, upstream elevation view of an arch assembly and truncated pyramid](figures/method1-arch-pyramid-upstream-elevation.png) *Upstream elevation view. Looking from the incoming-wind side toward the buildings shows the approach family separating around and above the forms. It is useful for checking the incoming direction and roof-level deflection, but the downstream wake is mostly hidden by the architecture from this camera position.* ![Method 1, plan view of an arch assembly and truncated pyramid](figures/method1-arch-pyramid-plan.png) *Plan view of the same study. Wind travels from the bottom of the viewport toward the top. The region above the objects is therefore downstream, where the tight, turning paths identify the disturbed wake and recovery region. This is the clearest view for comparing wake position, width, and interaction between the two forms.* ![Method 1, downstream side view of an arch assembly and truncated pyramid](figures/method1-arch-pyramid-downstream-side.png) *Downstream-side view of the same study. The paths bend around the tapered form and the arch, then reorganize after leaving the objects. The sheltered, tightly turning paths are easiest to recognize when the camera is on or beyond the downstream side.* The colors encode local speed according to the legend: cooler blue/cyan paths indicate the lower end of the displayed range, while green through yellow, orange, and red indicate higher speed. Color alone does not identify turbulence; read it together with the path direction, curvature, and position relative to the downstream side of the buildings. The yellow object outlines and transformation gizmo visible in these working screenshots are Rhino selection graphics, not AeroField output. Deselect the source geometry and hide the Gumball before capturing a presentation image, baking, or exporting a movie. These images are useful for learning the camera views; use a completed Standard field and record its Summary before relying on fine wake differences in a design comparison. ### 6.2 Method 2: Wake and Vortex Use Method 2 to inspect the downstream wake. It combines wake-oriented surfaces and selected guide paths to show where disturbed and rotating flow is concentrated. Read [Speed-Up](#82-speed-up-the-most-important-normalized-comparison) and [Wake, recirculation, and rotational indicators](#85-wake-recirculation-and-rotational-indicators) before comparing this view's colors or surface extent. Treat this as a comparative wake visualization. Thresholded surfaces depend on field resolution and should not be interpreted as exact physical boundaries. ![Oblique downstream view of Method 2, Wake and Vortex](figures/method2-arch-pyramid-downstream.png) *Figure 6.2: Method 2 viewed from the downstream side of the arch-and-tapered-form study. The translucent wake surface is shaped from vorticity magnitude, while its colors and the guide-path colors use the local speed-up scale shown in the viewport. The tightly looping dark-blue paths in the sheltered gap identify the most strongly turning portion of the displayed flow. Treat the surface as a thresholded locator for the wake, not as a solid boundary or a volume of air.* ### 6.3 Method 3: Pedestrian Wind Map Use Method 3 for a horizontal view at the Analysis Height. It displays a colored scalar map with contextual flow lines. Its default scalar is the same-height normalized quantity defined in [Speed-Up](#82-speed-up-the-most-important-normalized-comparison). The default field is speed-up ratio: - below `1.0`: slower than the local incoming wind; - near `1.0`: similar to the local incoming wind; - above `1.0`: accelerated relative to the local incoming wind. This view supports early comparisons of entrances, corners, passages, courtyards, and sheltered zones. It is not a comfort-certification result. ![Oblique downstream view of Method 3 with an unavailable pedestrian plane](figures/method3-arch-pyramid-downstream.png) *Figure 6.3: Method 3 safely preserves 3D context paths when the requested pedestrian plane cannot be sampled. In this study, the requested 1.50 m height is above the solved 0.00--0.11 m vertical range, so no horizontal color map is drawn. This is an unavailable-map state, not a pedestrian wind result. Choose an Analysis Height within the displayed solved range to produce the colored map.* ### 6.4 Method 4: Flow Sections Use Method 4 to inspect a scalar field through a section. The selected Section Field can show velocity, rotation, vertical movement, or another derived quantity. [Section 8](#8-flow-physics-colors-and-scalar-fields) defines the available fields, their units, signs, and interpretation limits. Choose this method when a three-dimensional path view is visually dense or when a specific vertical or horizontal pattern needs to be examined. ![Oblique downstream view of Method 4 with the horizontal section omitted](figures/method4-arch-pyramid-downstream.png) *Figure 6.4: Method 4 on the same study. The visible vertical section and guide paths remain available, while the requested horizontal section at 1.50 m is omitted because that height is outside the 0.00--0.11 m solved vertical range. The warning prevents an extrapolated slice from being mistaken for field data.* ### 6.5 Method 5: Surface Exposure Use Method 5 to compare relative exposure on building facades and roofs. Available surface fields are Speed-Up, Speed, and Pressure Proxy. See [Speed versus Speed-Up](#83-speed-versus-speed-up) and [Pressure Proxy and other comparison indicators](#86-pressure-proxy-and-other-comparison-indicators) for the physical distinctions and limits. This view is useful for comparing design alternatives and locating relatively exposed or sheltered surface regions. It does not provide facade design pressures. ![Oblique downstream view of Method 5, Surface Exposure](figures/method5-arch-pyramid-downstream.png) *Figure 6.5: Method 5 intentionally colors the building surfaces. This example uses Speed-Up, so the surface mesh and nearby guide paths share the fixed 0--2 local speed-up scale. Compare façade and roof regions against that legend; these colors indicate relative velocity exposure and are not pressure coefficients or façade-load values.* --- ## 7. AeroField Advanced Settings Reference ### 7.1 Wiring ```text AeroField Advanced Settings.Advanced Settings | v AeroField Study.Advanced Settings ``` The Advanced Settings component is optional. You can complete an ordinary study with only AeroField Study. Add Advanced Settings when you need to change a solver, domain, profile, path, scalar, or viewport option without turning the Study component into a wall of controls. The wiring rule is: 1. Add **AeroField Advanced Settings**. 2. Connect its `Advanced Settings` output to the Study component's `Advanced Settings` input. 3. Connect only the individual controls you want to change. When the Advanced Settings output is connected, it becomes authoritative and the Study component's `Quality` input is ignored. The Advanced Settings component uses **Standard** when `Base Quality` is unconnected. If you connect `Base Quality` to `Preview` or `Detailed`, every other unconnected port inherits that selected preset. A connected port always overrides the inherited value. For example, a Number Slider connected only to `Ground Elevation m` changes the ground elevation while all other settings remain at their Standard values. A Panel containing `Preview` connected to `Base Quality` deliberately selects the faster preset without requiring 23 additional wires. ### 7.2 Resolution and field size | Input | Preview inherited value | Standard value | Meaning | |---|---:|---:|---| | Base Quality | Standard | Standard | Starting preset for every unconnected advanced input | | Target Resolution | 8 cells across | 24 cells across | Target representation of the smallest significant building dimension | | Maximum Cells | 120,000 base budget | 1,500,000 | Upper limit for the calculated 3D field | | Allow Resolution Relaxation | False | False | Whether actual resolution may be reduced to fit the cell budget | The Detailed preset uses 32 target cells across and a 2,000,000-cell budget. These are inherited values, not promises that every case will reach the target. AeroField always attempts to return a field for valid finite geometry. If the target cannot fit, it automatically uses the finest full-domain grid that fits the active cell budget and reports the achieved resolution in Summary and Diagnostics. This can happen with broad ring or donut shapes, tall slender buildings, unusually large sites, or several separated buildings. The resulting field remains useful for comparative visualization, but small facade and wake structures may be under-resolved. Think of the two numerical controls as a tradeoff: - **Target Resolution** controls how many cells represent the smallest important building dimension. More cells show smaller features more clearly, but increase memory and calculation time. - **Maximum Cells** is a safety ceiling for the complete 3D field. Increasing it allows a requested resolution to fit, but also permits a larger memory allocation. - **Allow Resolution Relaxation** is an explicit way to request a particular minimum-resolution policy when you want to control the tradeoff yourself. Even when it is off, AeroField still returns a bounded approximation for valid geometry rather than failing solely because the nominal target exceeds the memory guard. For a 10 m cube, a 24-cell target corresponds to a nominal cell size of about 0.42 m across the cube. The actual field still depends on the complete domain around the cube, so the total cell count can be much larger than (24^3). If Summary reports 22 cells across instead of 24, compare the result using the achieved value, not the target value. ### 7.3 Incoming-wind profile | Input | Inherited value | Meaning | |---|---:|---| | Wind Profile | Power Law | Height-varying or uniform incoming speed | | Wind Reference Height m | Unconnected | Optional absolute height where Wind Speed applies | | Terrain Exponent | 0.22 | Strength of vertical wind shear | | Ground Elevation m | Inferred | Explicit world-Z ground elevation when connected | **Power Law** makes incoming speed vary with height. It is the normal conceptual setting for exterior building studies. **Uniform** applies the same incoming speed at every height and is useful for controlled geometry comparisons or diagnosing whether vertical shear is driving an effect. The reason AeroField compares Speed-Up to an incoming reference at the same height is explained in [Section 8.2](#82-speed-up-the-most-important-normalized-comparison). Leave `Wind Reference Height m` disconnected when the supplied Study wind speed should scale relative to the characteristic building height. Connect a positive height when the wind speed is known at an absolute physical elevation. For example, if a weather specification says that the reference speed is 10 m/s at 10 m above ground, connect a Number Slider or Panel containing `10` to `Wind Reference Height m` and keep the Study wind speed at `10`. `Terrain Exponent` affects only Power Law. A larger value makes the wind change more strongly with height. It is a conceptual roughness parameter, not a substitute for a project wind-climate study. `Ground Elevation m` is useful when the model is not sitting on world Z=0 or when the lowest building geometry is not a reliable ground reference. The value is in physical meters, even when the Rhino document uses millimeters, feet, or inches. Connecting `5` means that the calculated domain begins at world elevation 5 m and analysis heights are measured upward from that ground. ### 7.4 Calculated field extents | Input | Standard basis | Meaning | |---|---:|---| | Upwind Domain H | 5.0H | Calculated distance before the buildings | | Downwind Domain H | 5.0H | Calculated distance after the buildings | | Side Domain H | 1.5H | Lateral clearance on each side | | Top Domain H | 1.0H | Clearance above the tallest building | Here (H) is the characteristic height used by AeroField for the prepared building mass. These four controls change the calculated domain, not merely the picture: - **Upwind Domain H** creates solved space before the building. - **Downwind Domain H** creates solved space for the wake. - **Side Domain H** keeps lateral boundaries away from side passages. - **Top Domain H** creates solved space above the tallest mass. The normal Standard and Detailed defaults calculate equal 5H approach and wake regions, so ordinary Method 1 paths begin at the solved wind inlet, cross the site, and continue to the solved outlet. Preview uses equal 4.5H regions for a quicker initial result. Increasing any extent increases the field volume and can force a coarser grid under the same Maximum Cells limit. Increase `Upwind Domain H` only when the calculation itself needs more inlet-side space than the default, such as a long approach region or a site with upstream obstacles. Example: if the cube is 10 m high and `Downwind Domain H` is 5, the nominal downwind clearance is about 50 m. This can be valuable for studying a long wake, but it costs substantially more cells than a display-only approach extension. AeroField has no fixed maximum building height in meters or model units. The top of the field is constructed from the tallest connected mass plus `Top Domain H`; it is not clipped to a hidden absolute elevation. A very tall, slender tower can nevertheless require many cells because its height also enlarges the surrounding domain while its narrow footprint controls the desired cell size. For the untouched Standard preset, AeroField automatically uses the finest full-height grid that fits the 1,500,000-cell field budget when a tall, slender single building cannot fit the nominal 24-cell target. The same policy applies to donut or ring-shaped geometry and to any other valid site whose envelope makes the nominal target too expensive. This bounded fallback can reach the Preview floor of 8 cells across in the specialized tall-building path, or lower when the active budget requires it. The component remains usable and reports the achieved resolution, the strategy, and a remark that narrow facade and wake details may be under-resolved. The tower, ring, or other mass and the configured clearances remain in the solved domain; only the cell spacing is coarsened to stay within the memory guard. To obtain a finer target, connect Advanced Settings and raise `Maximum Cells` only when the computer can support it. Use the reported cells across when interpreting narrow shear layers or wake structure. ### 7.5 Detailed streamline controls | Input | Default | Meaning | |---|---:|---| | Detailed Streamlines | 150 | Method 1 target, accepted range 120 to 180 | | Upstream Approach H | Compatibility input | Retained for older Grasshopper definitions and ignored by current versions. Use Upwind Domain H for a longer physical inlet region. | | Detailed Line Width px | 2.0 | Method 1 line width, accepted range 0.8 to 3.0 | | Streamline Color Range | Robust Global | Color scaling policy | | Fixed Color Minimum m/s | 0 | Lower limit when Fixed is selected | | Fixed Color Maximum m/s | 20 | Upper limit when Fixed is selected | These controls are primarily for Method 1, Detailed 3D Streamlines. For the physical meaning of a streamline and the limits of its display density, see [Section 8.4](#84-what-streamlines-do-and-do-not-show): - **Detailed Streamlines** sets the target number of paths. It changes path density, not field resolution. - **Upstream Approach H** is retained for compatibility with older Grasshopper definitions and is ignored. Method 1 now displays only direct calculated traces. Use **Upwind Domain H** when the physical calculation needs a longer inlet region. - **Detailed Line Width px** changes the Method 1 stroke width in the Rhino viewport. It is not a physical diameter, does not create solid Rhino pipes, and does not change the calculated field. The 2.0 px default balances legibility with enough separation to read nearby paths and their velocity colors. Use approximately 0.8 to 1.5 px for very dense close-up comparisons, keep 2.0 px for normal modeling and review, and use 2.5 to 3.0 px for distant cameras or presentation captures. A wider stroke can hide fine curvature, merge neighboring paths, and cover short color transitions even though the underlying path and velocity samples are unchanged. Display scaling and monitor pixel density can also affect the apparent thickness, so judge this value in the Rhino view where the image will be reviewed or captured. - **Streamline Color Range** decides how velocity values map to colors. Line width and color policy do not repeat the main field calculation. Changing the detailed streamline count may rebuild Method 1 paths from the cached field, which is much cheaper than solving the field again. Color range choices: - `Robust Global`: uses robust limits across the displayed paths; - `Full Data`: uses the complete displayed minimum and maximum; - `Fixed`: uses the connected minimum and maximum. ### 7.6 Scalar display controls | Input | Default | Meaning | |---|---:|---| | Section Field | Speed-Up | Scalar used by Method 4 | | Surface Field | Speed-Up | Scalar used by Method 5 | | Analysis Plane Opacity | 0.25 | Opacity from 0 to 1 | | Context Line Width px | 2 | Guide-path width in Methods 2 through 5 | Section Field accepts: - Speed-Up; - Speed; - Pressure Proxy; - Vorticity; - Q Criterion; - Vertical Velocity; - Velocity X, Y, or Z; - Divergence; - Flow Disturbance; - Speed Deficit. Surface Field accepts Speed-Up, Speed, or Pressure Proxy. These fields change what is sampled and colored in the selected view. They do not create a new 2D or 3D calculation. Their definitions, units, signs, and limits are in [Section 8](#8-flow-physics-colors-and-scalar-fields). For example, to inspect the pressure proxy: 1. Connect Advanced Settings to Study. 2. Connect a Panel containing `Pressure Proxy` to `Section Field`. 3. Click Study visualization button **4**. 4. Read the legend and Diagnostics to confirm the selected field and range. To color building surfaces by local speed instead, connect `Speed` to `Surface Field` and click button **5**. `Surface Field` accepts fewer choices because it is sampled on the building boundary display. `Analysis Plane Opacity` controls how strongly the colored slice overlays the Rhino scene. Set it near `0` to see paths and the building more clearly; increase it when the scalar pattern itself is the focus. `Context Line Width px` changes the guide paths used by Methods 2 through 5. ### 7.7 Live viewport controls | Input | Default | Meaning | |---|---:|---| | Viewport Labels | True | Shows the AeroField title and status text in Rhino | | Color Legends | True | Shows live scalar legends in Rhino | These switches affect the live Rhino viewport. Movie frames always omit AeroField text, colorbars, legend axes, grid axes, and other foreground annotation. ### 7.8 Which settings recalculate? | Change | What AeroField does | |---|---| | Target Resolution, Maximum Cells, Allow Resolution Relaxation | Replans the field and may repeat the calculation | | Wind Profile, Wind Reference Height, Terrain Exponent | Rebuilds the incoming condition and repeats the calculation | | Ground Elevation or any solved domain extent | Rebuilds the prepared domain and repeats the calculation | | Detailed Streamlines | Rebuilds detailed paths from the stored field | | Upstream Approach H | Compatibility input; no effect in current versions | | Detailed Line Width px, color range | Updates the display without a new field solve | | Section Field, Surface Field, plane opacity | Resamples or recolors the existing result | | Context Line Width, Viewport Labels, Color Legends | Updates live display only | If a change is display-only, wait for the Study message to settle and then inspect the new view. There is no reason to wait for a full calculation when changing only a scalar field, legend, label, or line-width setting. ### 7.9 Worked recipes #### Recipe A: Keep Standard quality while overriding one setting 1. Add Advanced Settings and connect its output to Study. 2. Leave `Base Quality` disconnected; Standard is already the inherited preset. 3. Connect only the setting you want to override. The Study Quality input is ignored because Advanced Settings is authoritative. The remaining ports inherit Standard values, including 24 target cells across and a 1,500,000-cell field budget. #### Recipe B: Select Preview and increase the physical inlet region 1. Connect Advanced Settings to Study. 2. Connect a Panel containing `Preview` to Base Quality. 3. Connect a Number Slider set to `6.0` to `Upwind Domain H`. The solved inlet-side region grows by approximately 1.5 additional characteristic building heights beyond Preview's 4.5H default. This repeats the calculation and may increase the cell count, but every displayed incoming streamline remains a direct field trace. #### Recipe C: Use an explicit ground elevation 1. Connect Advanced Settings to Study. 2. Connect a Panel or Number Slider containing `5` to `Ground Elevation m`. 3. Recheck Summary for the interpreted ground and analysis elevation. Use this when the building sits at world Z=5 m. Do not use it to move the building; it tells AeroField where the physical ground is for the field and height interpretation. #### Recipe D: Compare two resolutions honestly 1. Keep wind, geometry, domain extents, and camera unchanged. 2. Connect `Standard` to Base Quality and record Summary's actual cells across and total cells. 3. Duplicate the definition and connect a different Target Resolution, such as `16` or `28`. 4. Compare results using the reported actual resolution and the same color range policy. If the target cannot fit Maximum Cells, either raise the budget after checking available memory or enable Allow Resolution Relaxation and document the resulting coarser value. Do not describe a relaxed 18-cell result as a 24-cell result. #### Recipe E: Show a pressure proxy slice without a new solve 1. Connect Advanced Settings to Study. 2. Connect `Pressure Proxy` to Section Field. 3. Select Method 4. 4. Leave the numerical settings unchanged. The section is rebuilt from the stored field. The legend identifies the field and units; treat the result as comparative, not as a calibrated pressure load. --- ## 8. Flow Physics, Colors, and Scalar Fields This chapter explains the *physical meaning* of the graphics. It intentionally describes the exterior-flow quantities and their limits, rather than the numerical machinery used to obtain them. ### 8.1 The primary result: a three-dimensional velocity field At each fluid location, AeroField stores a three-component velocity vector: `U = (Ux, Uy, Uz)` in meters per second. The vector gives both **direction** and **magnitude**. Its magnitude, called **Speed**, is: `|U| = sqrt(Ux^2 + Uy^2 + Uz^2)` Speed is always non-negative and has units of `m/s`. The individual `Velocity X`, `Velocity Y`, and `Velocity Z` fields are signed world-coordinate components. Positive and negative values refer to Rhino's world axes, not to upwind/downwind or left/right relative to the building. `Vertical Velocity` is the same world-Z component: positive values mean upward movement and negative values mean downward movement. The velocity field exists only in the modeled exterior air volume. Values within a building mass are not air results, and an unavailable horizontal plane is never extrapolated beyond the solved volume. ### 8.2 Speed-Up: the most important normalized comparison **Speed-Up** is a dimensionless ratio, not a speed in `m/s`: `Speed-Up = |U| / U_ref(z)` Here, `|U|` is the local speed and `U_ref(z)` is the undisturbed incoming speed at the **same height above ground**, `z`. In a Uniform wind profile, `U_ref(z)` equals the Study's Wind Speed everywhere. In a Power Law profile, the undisturbed incoming speed normally increases with height; the same-height reference removes that ordinary atmospheric variation before comparing building-induced acceleration or shelter. Interpret the ratio as follows: | Speed-Up | Meaning | Typical physical reading | |---:|---|---| | `1.0` | Local speed matches the undisturbed incoming reference at that height | Neither local acceleration nor local speed loss is indicated by the ratio. The direction may still be deflected. | | Greater than `1.0` | Local acceleration | Possible side-passages, corners, roof bypass, or channeling between masses. | | Less than `1.0` | Local speed reduction | Possible wake, shelter, stagnation region, or reduced-flow pocket. | | Near `0` | Very low local speed relative to the reference | A sheltered or recirculating region may be present; inspect path direction and the other fields before drawing a conclusion. | **Worked example.** If the undisturbed local reference at a particular height is `5 m/s` and the displayed local speed is `7.5 m/s`, the Speed-Up is `7.5 / 5 = 1.50`. If the local speed is `3.0 m/s` at the same reference, the Speed-Up is `0.60`. The same `3.0 m/s` means something different at a different height if the undisturbed reference there is different. Methods 3 and 5 use a fixed `0-2` Speed-Up legend by default. A value of `0` is the low end, `1` is the local undisturbed reference, and `2` is twice that reference. Values outside the displayed range use the end color, so a red value on this fixed scale means `2 or greater`, not necessarily exactly `2.00`. ### 8.3 Speed versus Speed-Up Use **Speed** when the question is physical velocity in `m/s`: for example, whether a particular exterior location is faster or slower in absolute terms under a specified wind input. Use **Speed-Up** when the question is how strongly geometry modifies the wind relative to its local incoming background. Speed-Up is especially useful when a height-varying wind profile is active. A roof-level speed can be higher than a pedestrian-level speed simply because of height; a ratio near `1.0` says that this difference is close to the expected incoming profile, whereas a ratio above or below `1.0` identifies a local building-related departure. ### 8.4 What streamlines do, and do not, show A streamline is a curve everywhere tangent to the stored velocity field. It is a directional drawing aid: it shows how the displayed field bends around, over, and behind the buildings. The curve color represents the field named by the legend; in Method 1 this is local velocity magnitude `U` in `m/s`, while guide paths in the other methods commonly use Speed-Up. Method 1 draws bounded, piecewise tangent-continuous presentation curves through the calculated, collision-checked samples and divides each physical segment into contiguous color spans. The geometry smoothing affects only the stroke; each span color is interpolated from that segment's neighboring `U` samples, and one shared legend maps equal values to equal colors across the complete path family. The automatic Standard field includes low-level, balanced incoming cross-flow variation, so calculated approach and bypass streamlines need not be perfectly straight or identical. This is field-derived motion, not a sinusoidal display effect. It should not create a persistent site-wide lateral bias, and it should not be interpreted as a direct measurement of turbulence intensity. Preview omits this evolving variation and uses less field-development effort, so it normally looks smoother and can understate fine wake differences. Every ordinary Method 1 path starts on the calculated inlet boundary and is integrated forward through the site to the calculated outlet as one continuous curve. AeroField neither appends far-field geometry nor joins separate curve pieces before the building. Wake-focused paths are the deliberate exception: they may begin inside the calculated wake so that local recirculation remains readable. Standard and Detailed provide equal 5H approach and wake space by default; Preview provides equal 4.5H space. Increase **Upwind Domain H** only when the calculation itself needs a longer physical inlet region. The retained **Upstream Approach H** input is ignored for compatibility with older Grasshopper definitions. Streamlines are not measured smoke trails, do not establish travel time, and are not a count of air volume or mass flow. Closely spaced curves can make a region easier to see, but their spacing is controlled by the display's seeding policy rather than by a physical flux measurement. Read a streamline family by its approach direction, deflection, curvature, and relation to building surfaces and the downstream region. ### 8.5 Wake, recirculation, and rotational indicators A **wake** is the downstream region in which the building has left the incoming flow disturbed. It can contain lower speed, directional turning, local reverse flow, and gradual recovery toward the incoming condition. A wake is not a single hard-edged object and it is not synonymous with turbulence. Method 2 uses a thresholded rotational indicator to locate a wake-oriented surface. The thresholded surface is useful for comparing wake position and organization, but its extent depends on the selected threshold and field resolution. It is not a solid boundary, a cloud of material, or a measured turbulent volume. The rotational and diagnostic fields have these meanings: | Field | Physical definition | Correct interpretation | |---|---|---| | **Vorticity magnitude** | Magnitude of the curl of velocity, `|curl(U)|`, in `1/s` | Highlights local rotation and shear. High values can occur near walls and sharp directional changes; they are **not** turbulence intensity. | | **Q Criterion** | A velocity-gradient quantity that compares local rotation with local strain, in `1/s^2` | Positive regions can help locate rotation-dominated structure. It is a visualization aid, not proof of turbulence or a vortex core with a uniquely defined boundary. | | **Divergence** | `div(U)`, in `1/s` | A continuity-quality diagnostic. For exterior incompressible flow it should generally remain small away from boundaries; localized values can reflect gradients, sampling, or resolution sensitivity. It is not a ventilation rate or a source/sink of air. | The terms **turbulence intensity**, **turbulent kinetic energy**, and **comfort exceedance** refer to different physical or statistical quantities. AeroField does not display them as certified engineering results. Do not infer them from a colorful or highly curved path alone. ### 8.6 Pressure Proxy and other comparison indicators **Pressure Proxy** is a signed, velocity-derived comparison quantity reported in pascal-like units: `Pressure Proxy = 0.5 * rho * (U_ref(z)^2 - |U|^2)` with `rho = 1.225 kg/m^3` for this display quantity. It is positive where local speed is below the same-height incoming reference, negative where the flow is faster, and near zero where the two speeds match. It can make stagnation-facing and accelerated regions easier to compare, but it is **not** static pressure, a pressure coefficient (`Cp`), facade pressure, cladding load, or structural design load. In particular, a proxy value of zero means equal local and reference speed; it does not mean zero atmospheric pressure. The remaining velocity-derived comparison fields are: | Field | Formula or basis | What it helps show | Important limit | |---|---|---|---| | **Flow Disturbance** | `abs(1 - Speed-Up)`, limited to `0-1` | Magnitude of departure from the local incoming reference, whether faster or slower | It does not distinguish acceleration from a deficit and is not turbulence intensity. | | **Speed Deficit** | `max(0, 1 - Speed-Up)` | Only the lower-speed portion of a wake or sheltered region | It intentionally reports zero in accelerated regions. | | **Surface Exposure** | Adjacent exterior-air samples around the displayed building surface | Relative facade and roof exposure in Method 5 | It is not a wall shear, a wall pressure, or a load calculation. | ### 8.7 Read the field name and legend before the color The same color has no universal meaning. Always identify: 1. the active visualization method; 2. the scalar field name; 3. the units; 4. the legend minimum and maximum; and 5. whether the range is fixed, robust, or based on the full data. For **unsigned** fields, the palette progresses from dark blue at the low end through cyan, green, yellow, and orange to red at the high end. Examples are Speed, Speed-Up, Vorticity magnitude, Flow Disturbance, and Speed Deficit. Blue Speed-Up does **not** mean a negative speed or cold air; it means the low end of the shown ratio. For **signed** fields, the diverging palette uses blue for the negative side, a light neutral color near zero, and red for the positive side. Pressure Proxy, Q Criterion, Divergence, Vertical Velocity, and individual velocity components are signed. The legend numbers, not color names alone, define the physical direction and magnitude. For robust ranges, isolated extreme values are intentionally ignored when choosing the visible endpoints so ordinary field variation remains readable. Values below or above the displayed endpoints use the end color. Use a fixed range when comparing alternatives; an automatic range can assign the same red color to different values in two separate studies. ### 8.8 Flat-looking colors or an ambiguous picture If a plot appears nearly uniform or does not tell a clear physical story: 1. verify the active field and units; 2. inspect the legend range and whether an end color is saturated; 3. choose a section or camera that crosses the approach, interaction, and downstream regions; 4. compare Speed and Speed-Up rather than relying on only one of them; 5. inspect velocity direction or streamlines before calling a region a wake or a vortex; 6. compare a second wind direction or geometry; 7. increase resolution only after confirming scale, placement, and the reported achieved resolution; and 8. use the same quality, field, and fixed color range for design-option comparisons. --- ## 9. Calculation and Display Updates AeroField separates the calculated field from its presentation. This keeps ordinary display changes responsive. ### 9.1 Changes that repeat the main calculation - building geometry; - Rhino unit conversion; - wind speed; - wind direction; - quality; - target resolution; - maximum cells when it changes the planned field; - resolution relaxation; - incoming-wind profile settings; - ground elevation; - calculated field extents. ### 9.2 Changes that reuse the field - analysis height; - visualization method buttons 1 through 5; - the legacy Upstream Approach H compatibility input; - line widths; - streamline color policy and fixed limits; - section field; - surface field; - analysis-plane opacity; - viewport labels; - color legends; - movie preparation and export; - baking. Changing Detailed Streamlines can repeat path integration from the cached field, but it does not repeat the main field calculation. ### 9.3 Automatic updates There is no Run input. Grasshopper automatically asks the Study to update when one of its inputs changes. The component reuses cached work whenever the changed input affects only presentation. To stop active work, right-click the Study and choose the cancellation command. The last valid result remains available when possible. --- ## 10. Baking to Rhino Grasshopper previews are temporary. Baking creates persistent Rhino objects that remain after Grasshopper preview is disabled. ### 10.1 Bake the active visualization 1. Select the desired visualization method. 2. Adjust the Rhino camera and any display settings. 3. Click **BAKE VIEW TO RHINO** on the Study component. 4. Inspect the newly created Rhino objects and layers. 5. Save the Rhino document. The button is enabled after a valid Study visualization exists. ### 10.2 Bake Flow Paths through standard Grasshopper tools The `Flow Paths` output contains ordinary curve geometry. It can also be connected to a Curve parameter and baked using Grasshopper's standard Bake command. This is useful when only the path curves are required. Avoid previewing both the Study and a downstream Curve parameter unless the duplicate display is intentional. --- ## 11. Animation Export ### 11.1 Complete wiring ```text AeroField Study.Study | v AeroField Animation Export.Study ``` No additional slider, panel, toggle, or filename input is required. ### 11.2 Prepare the camera The movie uses the active Rhino viewport camera. 1. Select the desired visualization method on the Study. 2. Orbit and zoom to frame the result. 3. Avoid changing the camera after the Animation Export reports that frames are ready. 4. If the camera changes, allow the component to prepare a matching set of frames. ### 11.3 Automatic frame preparation After a valid Study is connected, AeroField prepares between two and eight frames before the user requests a file. The exact count adapts to capture time. Two sufficiently different phases are the minimum fallback. The default frame size is Full HD: `1920 x 1080` pixels. Movie frames contain the visualization only. AeroField omits: - viewport title and status text drawn by AeroField; - scalar colorbars; - colorbar numbers and axes; - Rhino grid and grid axes; - explanatory foreground labels. ### 11.4 Export Movie Click **EXPORT MOVIE** to use an automatic timestamped filename in AeroField's movie output folder. On success: - `Movie Path` contains the full path; - the component status shows the saved filename; - Rhino reports the destination; - the operating system reveals the file. ### 11.5 Save As Click **SAVE AS...** to choose a folder, filename, and available format. AeroField scans the local `ffmpeg` installation and populates the file-type list with formats that can be encoded on that computer. Common detected formats include: - MP4; - MOV; - WebM; - MKV; - AVI; - GIF; - APNG. The exact list depends on the installed encoder. MP4 is the normal compatibility choice. MOV is useful in Apple-centered workflows, WebM for web use, and GIF or APNG for short looping graphics where their limitations are acceptable. ### 11.6 Movie appearance The movie animates packets along the current stored set of flow paths. It communicates direction and relative motion; it is not a time-accurate pathline simulation. The camera remains fixed so movement in the movie represents the graphics rather than camera motion. ### 11.7 When movie encoding is unavailable Install `ffmpeg`, restart Rhino, and reconnect the Study. AeroField retains prepared PNG frames when encoding fails so the images can be inspected or encoded separately. --- ## 12. Recommended Workflows ### 12.1 Massing comparison 1. Set correct Rhino units. 2. Use Preview quality. 3. Check wind direction with Method 1. 4. Compare the same camera and wind across design options. 5. Inspect Method 3 at pedestrian height. 6. Use Standard quality on shortlisted options. 7. Save Summary text with each option. ### 12.2 Pedestrian-level review 1. Set Analysis Height to the desired height above ground. 2. Select Method 3. 3. Inspect entrances, corners, passages, courtyards, and building gaps. 4. Compare more than one incoming direction. 5. Keep the color range and quality consistent across alternatives. ### 12.3 Wake review 1. Select Method 1 to verify the incoming direction and three-dimensional path distribution. 2. Select Method 2 to inspect the downstream wake. 3. Select Method 4 for a section through the wake. 4. Compare the wake length and organization across massing options. ### 12.4 Presentation graphics 1. Choose the clearest visualization for the design question. 2. Set the camera before preparing a movie. 3. Use live labels and legends while interpreting the result. 4. Turn them off for a clean still image if desired. 5. Bake the active view for Rhino documentation. 6. Connect Study to Animation Export for a clean movie without overlays. ### 12.5 Reproducible comparisons Hold these values constant across options: - units and physical scale; - wind speed and direction; - quality or explicit resolution; - calculated field extents; - analysis height; - scalar field and color-range policy; - camera and visualization method. Record any warning or best-effort status shown in Summary. --- ## 13. Warnings and Troubleshooting ### 13.1 Component colors | Grasshopper state | Meaning | |---|---| | Normal | No current warning or error | | Orange | A warning or interpretation limitation is present; a valid result may still exist | | Red | The current operation failed | Click the component balloon or connect Summary and Diagnostics to Panels to read the complete message. ### 13.2 Inspecting interpreted dimensions AeroField does not interrupt startup for small geometry. When physical scale matters to the interpretation, connect Summary or Diagnostics to a Panel to inspect the characteristic height, calculation domain, and model-to-meter conversion. ### 13.3 Analysis plane omitted The requested Analysis Height lies outside the calculated field. 1. Confirm that Analysis Height is measured above ground. 2. Check the inferred or explicit Ground Elevation. 3. Use a height inside the building and field range. 4. Increase Top Domain H only when a larger calculated vertical extent is genuinely required. Three-dimensional flow paths can remain valid even when the plane is omitted. ### 13.4 Resolution exceeds Maximum Cells The requested resolution and domain cannot fit the configured field-size guard. For valid finite geometry, AeroField now adapts the grid automatically and returns the finest full-domain field that fits the active budget. The component reports a **Budget-bounded fallback** remark when the nominal target cannot fit. Record the achieved resolution before comparing smaller wake structures. This is an approximation warning, not a failed study. If the achieved resolution is too coarse for the design question, try these actions in order: 1. verify that no distant or accidental geometry enlarges the site; 2. use Preview quality while setting up the study; 3. reduce unnecessary domain extents; 4. raise Maximum Cells only when adequate memory and time are available; 5. connect Advanced Settings and raise Maximum Cells when the computer can support a finer field; otherwise keep the bounded result and document its achieved resolution. ### 13.5 Maximum iterations or time budget reached AeroField Preview is intentionally time-bounded so the first connected study remains responsive. In a multi-building scene, AeroField may add one bounded pass of up to eight seconds when at least one substantial local wake remains weak after the initial Preview. If Summary reports that either budget was reached, the finite field is available for setup and visual inspection; use Standard or Detailed when wake width, recirculation, or smaller between-building differences matter. Read Summary and Diagnostics before making comparisons. ### 13.6 No visible flow paths 1. Confirm that the Study has a valid result. 2. Select Method 1. 3. Use Rhino `Zoom Extents` or frame the building. 4. Verify the wind direction. 5. Disable preview on duplicate downstream parameters. 6. Check whether Grasshopper preview is globally enabled. 7. Read Diagnostics for geometry or path-generation warnings. ### 13.7 Paths appear tilted or biased 1. Switch to a true plan or elevation view aligned with world axes. 2. Confirm the meteorological wind convention. 3. test a centered cube with a cardinal wind; 4. remove remote or asymmetric geometry; 5. confirm that the building base and ground are level; 6. allow the field to finish updating before judging symmetry. Perspective projection can make parallel paths appear tilted. A centered symmetric test should nevertheless show no persistent numerical left-right preference. ### 13.8 Upstream paths are too short Method 1 already calculates equal inlet and outlet extents by default: 5H for Standard and Detailed, or 4.5H for Preview. Connect Advanced Settings and increase `Upwind Domain H` only when the calculated inlet region itself needs more space. This repeats the calculation and may require a larger Maximum Cells budget, but it preserves one continuous physical trace from the solved inlet to the outlet. ### 13.9 Building is unexpectedly colored Method 5 intentionally colors building surfaces. Other methods may include translucent scalar surfaces that overlap the building from a particular camera angle. Select Method 1 for path-focused inspection or reduce Analysis Plane Opacity. AeroField suppresses the Study component's duplicate native previews for Flow Paths and Analysis Plane; if either output is connected to another preview-capable Grasshopper parameter, that downstream parameter may add its own preview and can be disabled when it duplicates AeroField's display. ### 13.10 Movie frames are not ready Keep the active Rhino camera still and allow frame preparation to finish. The component status reports progress and then shows the number of prepared Full HD frames. ### 13.11 Movie does not encode 1. Confirm that `ffmpeg` is installed. 2. choose a format shown in the Save As dialog; 3. choose a writable output folder; 4. inspect the retained frames if the encoder reports a failure; 5. reconnect the Study or restart Rhino after installing the encoder. ### 13.12 Duplicate plugin conflict Remove the extra `.gha` copy, keep its companion Core DLL with the retained assembly, and restart Rhino. Do not load differently named copies of the same AeroField assembly from multiple plugin folders. --- ## 14. Interpretation and Limitations ### 14.1 Appropriate use AeroField is well suited to: - early massing comparison; - qualitative flow-path review; - relative acceleration and shelter comparison; - deciding where a higher-fidelity study is warranted; - producing clear design-conversation graphics. ### 14.2 Uses requiring specialist analysis Do not rely on AeroField alone for: - structural wind loads; - facade pressure design; - pedestrian comfort certification; - code compliance; - life-safety decisions; - thermal or buoyancy effects; - indoor ventilation rates; - pollutant-dispersion certification. ### 14.3 Resolution awareness The field is represented on a regular three-dimensional grid. Geometry smaller than a few cells cannot be resolved reliably. Summary reports the achieved cell size and resolution. If a design decision depends on a small canopy, screen, parapet, opening, or facade detail, confirm that the field resolution can represent it. ### 14.4 Best comparison practice Comparisons are strongest when only one design variable changes at a time. Use the same field extents, resolution, wind, camera, scalar field, and color policy across alternatives. Keep the Summary text with exported images. --- ## 15. Quick Reference ### 15.1 Minimum study ```text Geometry -> AeroField Study.Geometry ``` ### 15.2 Optional advanced controls ```text AeroField Advanced Settings.Advanced Settings -> AeroField Study.Advanced Settings ``` ### 15.3 Movie ```text AeroField Study.Study -> AeroField Animation Export.Study ``` Wait for `Ready`, then click **EXPORT MOVIE** or **SAVE AS...**. ### 15.4 Default values | Setting | Default | |---|---:| | Wind Speed | 10 m/s | | Wind From | 0 degrees | | Analysis Height | 1.5 m | | Quality | Standard when unconnected | | Standard Target Resolution | 24 cells across | | Standard Maximum Cells | 1,500,000 | | Wind Profile | Power Law | | Terrain Exponent | 0.22 | | Upwind Domain | 5.0H | | Downwind Domain | 5.0H | | Side Domain | 1.5H per side | | Top Domain | 1.0H | | Detailed Streamlines | 150 | | Upstream Approach | Compatibility input; ignored | | Detailed Line Width | 2.0 px | | Context Line Width | 2 px | | Analysis Plane Opacity | 0.25 | | Movie Resolution | 1920 x 1080 | | Movie Frames | 2 to 8, prepared automatically | ### 15.5 Visualization chooser | Question | Method | |---|---| | How does air move around and over the mass? | 1 Detailed 3D Streamlines | | Where is the wake concentrated? | 2 Wake and Vortex | | What happens at pedestrian height? | 3 Pedestrian Wind Map | | What happens through a section? | 4 Flow Sections | | Which surfaces are relatively exposed? | 5 Surface Exposure | ### 15.6 Essential reminders - Check Rhino units before calculating. - `Wind From` describes the incoming direction. - The Study updates automatically. - An orange component may still contain a valid result; read the message. - Display changes normally reuse the calculated field. - Use `Upwind Domain H` when the calculated inlet-side region needs to be longer; Method 1 does not append artificial upstream path segments. - Movie frames are Full HD and contain no AeroField text or colorbar. - Bake the active view when persistent Rhino geometry is required. - Use consistent settings for design comparisons. - Treat AeroField as an early-design comparison tool, not final engineering certification.