# VS:Energos Thirdparty Support

Energy Analysis is a plugin which uses data from objects in the Vectorworks document to calculate energy performance of a 3D building. It provides the user with a graphical and numerical feedback. It provides also a set of functions to give the ability to include third-party objects into energy calculations.

This document explains how to use the set of script functions to include third-party objects to the energy calculation.

The set of energy script functions are grouped in several categories.

## Contents |

### Unit conversion support

Energy analysis module uses distinct units from documents units for calculation. This group of functions supports the conversion between the SI unit system and the local unit system. The local unit system is defined in an XML file (EnergyUnits.xml), located in default libraries. In the table below are shown the units used by the energy analysis module. Column “Unit type” shows the INTEGER representations of unit type used by script functions.

Measure | SI | Imperial US | Unit type (INTEGER representation) |
---|---|---|---|

Area | Square millimeters [mm2] | Square inches [in2] | 6 |

Area | Square meters [m2] | Square foot [ft2] | 7 |

CO2 Emission (annually) | Kilograms per square meter per year [kg/(m2a)] |
Pounds per square foot per year [lb/(ft2a)] | 27 |

Electric consumptions | Watt-hour per cubic meter [Wh/m3] | British thermal unit per hour per cubic foot [Btu/h/ft3] | 24 |

Energy | Watt-hour [Wh] | British thermal unit [Btu] | 17 |

Energy | Kilowatt-hour [kWh] | British thermal unit [Btu] | 18 |

Energy (annually) | Kilowatt-hour per year [kWh/a] | British thermal unit per year [Btu/a] | 19 |

Energy (daily) | Kilowatt-hour per day [kWh/d] | British thermal unit per day[Btu/d] | 20 |

Energy flux | Watt per square meter [W/m2] | British thermal unit per hour per square foot [Btu/h ft2] | 23 |

Flow rate | Cubic meter per hour [m3/h] | Cubic feet per minute [CFM] | 16 |

Heat storage capacity of construction when its temperature varies 1 K | [Wh/m2 K] | [Btu/ft2 F] | 25 |

Heating degree hours (Gt) | Kilo-Kelvin hours per year [kKh/a] | Kilo degree Fahrenheit per year [kFh/a] | 30 |

Length | Millimeter [mm] | Inch [in] | 4 |

Length | Meter [m] | Foot [m] | 5 |

Percentage | Percent [%] Range: 0 - 100 |
Percent [%] Range: 0 - 100 |
2 |

Percentage [normalized] | Percent normal [%] Range: 0 - 1 |
Percent normal [%] Range: 0 - 1 |
3 |

Power | Watt [W] | British thermal units per hour [Btu/h] | 21 |

Power | Kilowatt [kW] | British thermal units per hour [Btu/h] | 22 |

Solar radiation (annually) | Kilowatt hour per square meter per year [kWh/m2/a] |
British thermal units per squared feet per year [Btu/ft2/a] | 12 |

Solar radiation (monthly) | Kilowatt hour per square meter per month [kWh/m2/month] |
British thermal units per squared feet per month [Btu/ft2/month] | 11 |

Temperature | Celsius [C] | Fahrenheit [F] | 10 |

Temperature difference | Kelvin [K] | Fahrenheit [F] | 29 |

Thermal conductivity | Watt per meter per Kelvin [W/m K] | British thermal unit per foot per hour per Fahrenheit degree [Btu/ft h F] |
15 |

Thermal heat transfer coefficient (U - value) |
Watt per square meter per Kelvin [W/(m2K)] | British thermal unit per square foot per hour per Fahrenheit degree [Btu/h ft2 F] |
14 |

Thermal resistance coefficient (R - value) |
Kelvin meter squared per watt [[m2K]/W] | Square foot degrees Fahrenheit hours per British thermal unit [[ft2 F h]/Btu] |
13 |

Velocity | Meter per second [m/s] | Feet per second [fps] | 31 |

Volume | Cubic millimeter [mm3] | Cubic inch [in3] | 8 |

Volume | Cubic meter [m3] | Cubic foot [ft3] | 9 |

Volume | Liter [l] | Gallon [gallon] | 28 |

Volumetric heat capacity | Mega joule per cubic meter Kelvin [MJ/m3K] | British thermal unit per square foot degree Fahrenheit [Btu/ft3 F] |
26 |

Air permeability at 50 Pa, noted q50 or qa50 | Cubic meter per hour per squared meter [m3/(h·m2] |
Cubic feet per minute per square foot [CFM/ft2] | 27 |

It is strongly recommended to use energy analysis functions to convert values. All functions provided by energy analysis module use meters, square meter, cubic meters, etc.

The list of functions which converts is:

- VS:EA_ConvDoc2X
- VS:EA_ConvStr2X
- VS:EA_ConvX2Doc
- VS:EA_ConvX2DocStr
- VS:EA_IsUsedUValue
- VS:EA_GetUnitStr
- VS:EA_UValueText

### Objects support (for space, window/door, wall, slab and roof)

There are several objects which are included in energy analysis calculations. They are spaces, windows, doors, walls, slabs and roofs. All building elements use the functions described below to get/set/save energy data in objects and that happens with support from energy analysis plugin. Energy analysis plugin attaches energy data node to each object who is involved into energy calculation. All the functions which set data are mandatory. Otherwise the energy analysis module won’t handle the object properly or will exclude it from calculation.

The functions below are applicable after create an accessor to object and copy energy data. The values of parameter *valueIndex* are listed in the table below and are grouped by object type.

- VS:EA_DataAccGetStr
- VS:EA_DataAccSetStr
- VS:EA_DataAccGetReal
- VS:EA_DataAccSetReal
- VS:EA_DataAccGetBool
- VS:EA_DataAccSetBool
- VS:EA_DataAccGetInt
- VS:EA_DataAccSetInt

Description | Value |
---|---|

Space object: create accessor | 100 |

Space object: include object to calculation | 101 |

Space object: name of the object as it is shown in the energy analysis dialog | 102 |

Space object: height of space in meters | 103 |

Space object: area in square meters | 104 |

Space object: area factor. The area factor is a numeric value who is multiplied by the space area (calculated or set by user). It is used to correct the area. | 105 |

Space object: volume of the space in cubic meters | 106 |

Window/door: create accessor | 200 |

Window/door: include object to calculation | 201 |

Window/door: type of the object. 0 - Window, 1 – Door, 2 - Window/Door(Window/Door is available from Vectorworks 2018). Windows are included in calculations to determine the depth and the width of the areas. Doors are not. Window/Doors are hybrid objects consisting of door and window. |
202 |

Window/door: name of the object as it is shown in the energy analysis dialog | 203 |

Window/door: area in square meters. The area includes glass and frame. The hole in the wall for the window has this area. The area = width * height. | 204 |

Window/door: width in meters. The width includes the window frame. | 205 |

Window/door: glazing area in square meters. In the sample glazing area = glass width * glass height. If object type is window/door in Vectorworks 2018, use only for window glazing area. | 206 |

Window/door: glazing length in meters. In the sample glazing length = 2*glass width + 2*glass height. If object type is window/door in Vectorworks 2018, use only for window glazing length. | 207 |

Window/door: frame length in meters. In the sample the frame length = 2*frame width + 2*frame height. If object type is window/door in Vectorworks 2018, use only for window frame length. | 208 |

Window/door: U-Value calculation mode. 0 - Automatic, 1 - Manual. | 209 |

Window/door: U – value in [W/(m2 K)]. Calculate R – value in this way: R = 1 / U. | 210 |

Window/door: auto calculated U - Value in [W/(m2 K)]. | 211 |

Window/door: clear width in meters. | 212 |

Window/door: clear height in meters. | 213 |

Window/door: clear area in square meters. In the sample clear area = clear width * clear height. | 214 |

Window/door: height from floor in meters. | 215 |

Window/door: tilting - if the window has tilting. Tilting affects the summer ventilation options of the window. They are available in advanced settings window/door dialog. | 216 |

Window/door: frame data uses popup control. Energy analysis tool uses these framing options for calculations. It does not extract data from the geometry of the object. The frame systems could be specified and managed by the user. | 217 |

Window/door: glazing system data uses popup control. Energy analysis tool uses these glazing options for calculations. It does not extract data from the geometry of the object. The glazing systems could be specified and managed by the user. | 218 |

Window/door: general shading data uses popup control. Energy analysis tool uses these shading options for calculations. The value is a percentage. | 219 |

Window/door: surrounding shading uses popup control. The value is a percentage. | 220 |

Window/door: summer shading uses popup control. The value is a percentage. | 221 |

Window/door: additional shading uses popup control. The value is a percentage. | 222 |

Door: is used door type system. (Availability: from Vectorworks 2017) | 223 |

Door: door type system data uses popup control. Energy analysis tool uses these door type options for calculations. It does not extract data from the geometry of the object. The door type systems could be specified and managed by the user. (Availability: from Vectorworks 2017) |
224 |

Hybrid Door: glazing area in square meters. In the sample glazing area = door glass width * door glass height. (Availability: from Vectorworks 2018) | 225 |

Hybrid Door: glazing length in meters. In the sample glazing length = 2* door glass width + 2* door glass height. (Availability: from Vectorworks 2018) | 226 |

Hybrid Door: frame length in meters. In the sample the frame length = door frame width + door frame height + 2* door frame thickness. (Availability: from Vectorworks 2018) | 227 |

Hybrid Door: frame area in square meters. In the sample frame area = door frame width * door frame height - door glass width * door glass height. (Availability: from Vectorworks 2018) | 228 |

Hybrid Window: frame area in square meters. In the sample frame area = window frame width * window frame height - window glass width * window glass height. (Availability: from Vectorworks 2018) | 229 |

Wall: create accessor | 300 |

Wall: include object to calculation | 301 |

Wall: name of the object as it is shown in the energy analysis dialog | 302 |

Wall: area in square meters | 303 |

Wall: U-Value calculation mode. 0 - Automatic, 1 - Manual. | 304 |

Wall: U – value in [W/(m2 K)]. Calculate R – value in this way: R = 1 / U | 305 |

Wall: auto calculated U - Value in [W/(m2 K)] | 306 |

Wall: boundary type uses popup control | 307 |

Slab: create accessor | 400 |

Slab: include object to calculation | 401 |

Slab: name of the object as it is shown in the energy analysis dialog | 402 |

Slab: area in square meters | 403 |

Slab U-Value calculation mode. 0 - Automatic, 1 - Manual. | 404 |

Slab: U – value in [W/(m2 K)]. Calculate R – value in this way: R = 1 / U | 405 |

Slab auto calculated U - Value in [W/(m2 K)] | 406 |

Slab: boundary type uses popup control | 407 |

Roof: create accessor | 500 |

Roof: include object to calculation | 501 |

Roof: name of the object as it is shown in the energy analysis dialog | 502 |

Roof: area in square meters | 503 |

Roof: U-Value calculation mode. 0 - Automatic, 1 - Manual. | 504 |

Roof: U – value in [W/(m2 K)]. Calculate R – value in this way: R = 1 / U | 505 |

Roof: auto calculated U - Value in [W/(m2 K)] | 506 |

Roof: boundary type uses popup control | 507 |

Curtain wall: create accessor | 600 |

Curtain wall: name of the object as it is shown in the energy analysis dialog | 601 |

Curtain wall: area in square meters | 602 |

Curtain wall: create accessor for a frame. | 700 |

Curtain wall: include the frame to calculation | 701 |

Curtain wall: frame area in square meters | 702 |

Curtain wall: connected length in meters. Connected length is the combined perimeter of all panels. | 703 |

Curtain wall: unconnected length In meters. Unconnected length is the outer perimeter of the curtain wall combined with perimeters of all open panels | 704 |

Curtain wall: frame data uses popup control. Energy analysis tool uses these framing options for calculations. It does not extract data from the geometry of the object. The frame systems could be specified and managed by the user. | 705 |

Curtain wall: general shading data uses popup control. Energy analysis tool uses these shading options for calculations. The value is a percentage. | 706 |

Curtain wall: surrounding shading uses popup control. The value is a percentage. | 707 |

Curtain wall: summer shading uses popup control. The value is a percentage. | 708 |

Curtain wall: additional shading uses popup control. The value is a percentage. | 709 |

Curtain wall: create accessor for panel. | 800 |

Curtain wall: include the panel to calculation | 801 |

Curtain wall: area in square meters | 802 |

Curtain wall: panel system data uses popup control. Energy analysis tool uses these options for calculations. It does not extract data from the geometry of the object. The panel systems could be specified and managed by the user. | 803 |

Curtain wall: general shading data uses popup control. Energy analysis tool uses these shading options for calculations. The value is a percentage. | 804 |

Curtain wall: surrounding shading uses popup control. The value is a percentage. | 805 |

Curtain wall: summer shading uses popup control. The value is a percentage. | 806 |

Curtain wall: additional shading uses popup control. The value is a percentage. | 807 |

### Object components support (for wall, slab and roof only)

Wall, slab and roof object have components. The functions below manage the components.

### User interface support

Objects which use energy data need user interface changes. Except the popups and edit fields some of the objcts have external system data and it is magaged via popups.

**Space** object does not have special controls.

**Window/door** preference dialog must have popups for frame, glazing and shading settings. They are provided by the energy analysis module. The only thing which should be done is to specify the popup as energy popup. Also event hander should use energy plugin to process the event.

**Wall**, **roof** and **slab** have boundary type popup.