Modify and Visualize an EnergyPlus Model Geometry

Source: R/geom.R

IdfGeometry is an abstraction of a collection of geometry in an Idf. It provides more detail methods to query geometry properties, update geometry vertices and visualize geometry in 3D using the rgl package.

idf_geometry(parent, object = NULL)

Arguments

parent

A path to an IDF file or an Idf object.

object

A character vector of valid names or an integer vector of valid IDs of objects to extract. If NULL, all objects in geometry classes will be extracted.

Value

An IdfGeometry object.

See also

Idf class

Author

Hongyuan Jia

Methods

Public methods

Method new()

Create an IdfGeometry object

Usage

IdfGeometry$new(parent, object = NULL)

Arguments

parent

A path to an IDF file or an Idf object.

object

A character vector of valid names or an integer vector of valid IDs of objects to extract. If NULL, all objects in geometry classes will be extracted.

Returns

An IdfGeometry object.

Examples

\dontrun{
# example model shipped with eplusr from EnergyPlus v8.8
path_idf <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr") # v8.8

# create from an Idf object
idf <- read_idf(path_idf, use_idd(8.8, "auto"))
geom <- idf$geometry()
geom <- IdfGeometry$new(idf)

# create from an IDF file
geom <- idf_geometry(path_idf)
geom <- IdfGeometry$new(path_idf)
}

Method parent()

Get parent Idf object

Usage

IdfGeometry$parent()

Details

$parent() returns the parent Idf object of current IdfGeometry object.

Returns

An Idf object.

Examples

\dontrun{
geom$parent()
}

Method rules()

Get global geometry rules

Usage

IdfGeometry$rules()

Details

$rules() returns global geometry rules.

Returns

An Idf object.

Examples

\dontrun{
geom$rules()
}

Method convert()

Convert simple geometry objects

Usage

IdfGeometry$convert(type = c("surface", "subsurface", "shading"))

Arguments

type

A character vector giving what types of simplified geometries should be converted. Should be a subset of "surface", "subsurface" and "shading". Default is set to all of them.

Details

EnergyPlus provides several classes that allow for simplified entry of geometries, such as Wall:Exterior, Window and etc. $convert() will generate detailed vertices from simplified geometry specifications and replace the original object with its corresponding detailed class, including:

  • BuildingSurface:Detailed

  • FenestrationSurface:Detailed

  • Shading:Site:Detailed

  • Shading:Building:Detailed

  • Shading:Zone:Detailed

Returns

The modified Idf object.

Examples

\dontrun{
geom$convert()
}

Method coord_system()

Convert vertices to specified coordinate systems

Usage

IdfGeometry$coord_system(detailed = NULL, simple = NULL, daylighting = NULL)

Arguments

detailed, simple, daylighting

A string specifying the coordinate system for detailed geometries, simple (rectangular surface) geometries, and daylighting reference points. Should be one of "relative", "world" and "absolute". "absolute" is the same as "world" and converted to it.

Details

$coord_system() converts all vertices of geometries into specified coordinate systems, e.g. from world to relative, and vice versa. Besides, it also updates the GlobalGeometryRules in parent Idf accordingly.

Returns

The modified Idf object.

Examples

\dontrun{
geom$coord_system("world", "world", "world")
}

Method round_digits()

Round digits on geometry vertices

Usage

IdfGeometry$round_digits(digits = 4L)

Arguments

digits

An integer giving the number of decimal places to be used. Default: 4.

Details

$round_digits() performs number rounding on vertices of detailed geometry object vertices, e.g. BuildingSurface:Detailed, FenestrationSurface:Detailed and etc.

$round_digits() may be useful for clean up IDF files generated using OpenStudio which often gives vertices with long trailing digits.

Returns

The modified Idf object.

Examples

\dontrun{
geom$round_digits()
}

Method area()

Get area

Usage

IdfGeometry$area(class = NULL, object = NULL, net = FALSE)

Arguments

class

A character vector of valid geometry class names. Default: NULL.

object

A character vector of valid names or an integer vector of valid IDs of targeting objects. Default: NULL.

net

If TRUE, the gross area is returned. If FALSE, the net area is returned. Default: FALSE.

Details

$area() returns the area of surfaces in square meters.

Returns

A data.table::data.table() of 6 columns:

  • id: Integer type. Object IDs.

  • name: Character type. Object names.

  • class: Character type. Class names.

  • zone: Character type. Zone names that specified objects belong to.

  • space: Character type. Space names that specified objects belong to.

  • type: Character type. Surface types.

  • area: Numeric type. Surface Area in m2.

Examples

\dontrun{
geom$area()
}

Method azimuth()

Get azimuth

Usage

IdfGeometry$azimuth(class = NULL, object = NULL)

Arguments

class

A character vector of valid geometry class names. Default: NULL.

object

A character vector of valid names or an integer vector of valid IDs of targeting objects. Default: NULL.

Details

$azimuth() returns the azimuth of surfaces in degree.

Returns

A data.table::data.table() of 6 columns:

  • id: Integer type. Object IDs.

  • name: Character type. Object names.

  • class: Character type. Class names.

  • zone: Character type. Zone names that specified objects belong to.

  • space: Character type. Space names that specified objects belong to.

  • type: Character type. Surface types.

  • azimuth: Numeric type. Azimuth in degree.

Examples

\dontrun{
geom$azimuth()
}

Method tilt()

Get tilt

Usage

IdfGeometry$tilt(class = NULL, object = NULL)

Arguments

class

A character vector of valid geometry class names. Default: NULL.

object

A character vector of valid names or an integer vector of valid IDs of targeting objects. Default: NULL.

Details

$tilt() returns the tilt of surfaces in degree.

Returns

A data.table::data.table() of 6 columns:

  • id: Integer type. Object IDs.

  • name: Character type. Object names.

  • class: Character type. Class names.

  • zone: Character type. Zone names that specified objects belong to.

  • space: Character type. Space names that specified objects belong to.

  • type: Character type. Surface types.

  • tilt: Numeric type. Azimuth in degree.

Examples

\dontrun{
geom$tilt()
}

Method view()

View 3D geometry

Usage

IdfGeometry$view(
  new = FALSE,
  render_by = "surface_type",
  wireframe = TRUE,
  x_ray = FALSE,
  axis = TRUE
)

Arguments

new

If TRUE, a new rgl window will be open using rgl::open3d(). If FALSE, existing rgl window will be reused if possible. Default: FALSE.

render_by

A single string specifying the way of rendering the geometry. Possible values are:

  • "surface_type": Default. Render the model by surface type model. Walls, roofs, windows, doors, floors, and shading surfaces will have unique colors.

  • "boundary": Render the model by outside boundary condition. Only surfaces that have boundary conditions will be rendered with a color. All other surfaces will be white.

  • "construction": Render the model by surface constructions.

  • "zone": Render the model by zones assigned.

  • "space": Render the model by spaces assigned.

  • "normal": Render the model by surface normal. The outside face of a heat transfer face will be rendered as white and the inside face will be rendered as red.

wireframe

If TRUE, the wireframe of each surface will be shown. Default: TRUE.

x_ray

If TRUE, all surfaces will be rendered translucently. Default: FALSE.

axis

If TRUE, the X, Y and Z axes will be drawn at the global origin. Default: TRUE.

Details

$view() uses the rgl package to visualize the IDF geometry in 3D in a similar way as OpenStudio.

$view() returns an IdfViewer object which can be used to further tweak the viewer scene.

In the rgl window, you can control the view using your mouse:

  • Left button: Trackball

  • Right button: Pan projection.

  • Wheel: Zoom

For more detailed control on the scene, see IdfViewer.

Returns

An IdfViewer object

Examples

\dontrun{
idf$view()
idf$view(render_by = "zone")
idf$view(new = TRUE, render_by = "construction")
}

Method print()

Print an IdfGeometry object

Usage

IdfGeometry$print()

Returns

The IdfGeometry itself, invisibly.

Examples

\dontrun{
geom$print()
}

Examples


## ------------------------------------------------
## Method `IdfGeometry$new`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# example model shipped with eplusr from EnergyPlus v8.8
path_idf <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr") # v8.8

# create from an Idf object
idf <- read_idf(path_idf, use_idd(8.8, "auto"))
geom <- idf$geometry()
geom <- IdfGeometry$new(idf)

# create from an IDF file
geom <- idf_geometry(path_idf)
geom <- IdfGeometry$new(path_idf)
} # }

## ------------------------------------------------
## Method `IdfGeometry$parent`
## ------------------------------------------------

if (FALSE) { # \dontrun{
geom$parent()
} # }

## ------------------------------------------------
## Method `IdfGeometry$rules`
## ------------------------------------------------

if (FALSE) { # \dontrun{
geom$rules()
} # }

## ------------------------------------------------
## Method `IdfGeometry$convert`
## ------------------------------------------------

if (FALSE) { # \dontrun{
geom$convert()
} # }

## ------------------------------------------------
## Method `IdfGeometry$coord_system`
## ------------------------------------------------

if (FALSE) { # \dontrun{
geom$coord_system("world", "world", "world")
} # }

## ------------------------------------------------
## Method `IdfGeometry$round_digits`
## ------------------------------------------------

if (FALSE) { # \dontrun{
geom$round_digits()
} # }

## ------------------------------------------------
## Method `IdfGeometry$area`
## ------------------------------------------------

if (FALSE) { # \dontrun{
geom$area()
} # }

## ------------------------------------------------
## Method `IdfGeometry$azimuth`
## ------------------------------------------------

if (FALSE) { # \dontrun{
geom$azimuth()
} # }

## ------------------------------------------------
## Method `IdfGeometry$tilt`
## ------------------------------------------------

if (FALSE) { # \dontrun{
geom$tilt()
} # }

## ------------------------------------------------
## Method `IdfGeometry$view`
## ------------------------------------------------

if (FALSE) { # \dontrun{
idf$view()
idf$view(render_by = "zone")
idf$view(new = TRUE, render_by = "construction")
} # }

## ------------------------------------------------
## Method `IdfGeometry$print`
## ------------------------------------------------

if (FALSE) { # \dontrun{
geom$print()
} # }