In hongyuanjia/eplusr: A Toolkit for Using Whole Building Simulation Program 'EnergyPlus'

knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    screenshot.force = FALSE,
    fig.align = "center",
    out.lines = 20
)

# the default output hook
hook_output <- knitr::knit_hooks$get("output")
knitr::knit_hooks$set(output = function(x, options) {
    if (!is.null(n <- options$out.lines)) {
        x <- unlist(strsplit(x, "\n", fixed = TRUE))
        if (length(x) > n) {
            # truncate the output
            x <- c(head(x, n), "....", "")
        } else {
            x <- c(x, "")
        }
        x <- paste(x, collapse = "\n") # paste first n lines together
    }
    hook_output(x, options)
})

options(crayon.enabled = FALSE)
options(data.table.print.class = TRUE)

library(eplusr)
if (!is_avail_eplus("23.1")) install_eplus("23.1")

This vignette introduces the IdfGeometry and IdfViewer classes. IdfGeometry is designed to extract data for all geometry objects and perform geometric operations on them, while IdfViewer is to view IDF geoemtry in 3D using the rgl package in a similar way as OpenStudio SketchUp Plugin.

---

Extract all geometry data

All geometry data in an Idf object can be extracted using the Idf$geometry(). What it returns is an IdfGeometry which parses all geometry related objects, including:

• GlobalGeometryRules
• Building
• Zone
• All geometry related classes in the Thermal Zones and Surfaces group and Daylighting group

path_idf <- file.path(eplus_config(23.1)$dir, "ExampleFiles/HospitalLowEnergy.idf")
idf <- read_idf(path_idf)
geom <- idf$geometry()
geom

Get geometry data

Get geometry rules

geom$rules()

Get surface area

geom$area()

By default, $area() returns areas of all surfaces in current Idf. You can specify class and object to only calculate objects of interest. This is also true for the $azimuth() and $tilt() methods.

geom$area(class = "Shading:Zone:Detailed")

With net being TRUE, the window and door areas will be excluded in the results of surfaces.

geom$area()[type == "Wall"]
geom$area(net = TRUE)[type == "Wall"]

Get surface azimuth and tilt

geom$azimuth()
geom$tilt()

Convert simple geometry

$convert() 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

path_simple <- path_eplus_example("23.1", "4ZoneWithShading_Simple_1.idf")
simple <- read_idf(path_simple)

simple$class_name(by_group = TRUE)["Thermal Zones and Surfaces"]

simple$geometry()$convert()

simple$class_name(by_group = TRUE)["Thermal Zones and Surfaces"]

An attribute named mapping is attached in the converted Idf object which contains the meta data of objects before and after the conversion.

attr(simple, "mapping")

Change coordinate systems

$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.

geom$rules()

geom$parent()$to_table("Floor 1 Cafe Slab")

geom$coord_system("world")

geom$parent()$to_table("Floor 1 Cafe Slab")

Round vertices decimal digits

$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.

geom$round_digits(3)

geom$parent()$to_table("Floor 1 Cafe Slab")

View geometry in 3D

$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, the default mouse modes are:

• Left button: Trackball
• Right button: Pan
• Middle button: Field-of-view (FOV). '0' means orthographic projection.
• Wheel: Zoom

viewer <- geom$view()

knitr::include_graphics("geom-viewer_default.png")

Tweak the view

The IdfViewer class provides a number of methods to tweak the view in a similar style as the OpenStudio SketchUp Plugin:

| Method | Functionality | | :--- | :--- | | $background() | Change background | | $viewpoint() | Change the viewpoint | | $mouse_mode() | Change the mouse controls | | $axis() | Add or remove axis, or tweak the style of axis. | | $ground() | Add or remove the ground, or tweak the style of ground. | | $wireframe() | Turn on/off wireframes. | | $x_ray() | Turn on/of X-ray style. | | $render_by() | Change how surfaces should be colored. | | $show() | Change what components/zones/surfaces to show |

Below shows the effects of each method:

Change background

viewer$background("grey50")

knitr::include_graphics("geom-viewer_background1.png")

viewer$background("white")

knitr::include_graphics("geom-viewer_background2.png")

Change viewpoint

viewer$viewpoint("top")

knitr::include_graphics("geom-viewer_viewpoint1.png")

viewer$viewpoint("iso")

knitr::include_graphics("geom-viewer_viewpoint2.png")

Change axis style

viewer$axis(width = 5)

knitr::include_graphics("geom-viewer_axis.png")

viewer$axis(FALSE)

knitr::include_graphics("geom-viewer_noaxis.png")

Change ground style

viewer$ground(TRUE)

knitr::include_graphics("geom-viewer_ground.png")

Turn on/off X-ray style

viewer$x_ray(TRUE)

knitr::include_graphics("geom-viewer_xray.png")

viewer$x_ray(FALSE)

knitr::include_graphics("geom-viewer_ground.png")

Change render style

viewer$render_by("zone")

knitr::include_graphics("geom-viewer_zone_color.png")

viewer$render_by("surface_type")

knitr::include_graphics("geom-viewer_ground.png")

Turn on/off components

viewer$show(zone = "floor 7 clean")

knitr::include_graphics("geom-viewer_show_zone.png")

viewer$show(surface = "MOB Floor 5 Perimeter 2 Ext Wall")

knitr::include_graphics("geom-viewer_show_surface.png")

viewer$show(type = "wall")

knitr::include_graphics("geom-viewer_show_wall.png")

Save the snapshot

$snapshot() captures the current rgl view and saves it as an image file to disk.

viewer$show()
viewer$snapshot("view.png")

knitr::include_graphics("geom-viewer_ground.png")

Work with the rgl window

$win_size() lets you control the size of the rgl window. $focus() brings the rgl window to the top. $close() closes the rgl window.

Summary

The IdfGeometry and IdfViewer classes provide utilities to work and visualize model geometries.

Currently, IdfGeometry is still evolving and more methods will be added to perform geometric transformations in the near future.

Also, new methods will be added in IdfViewer to allow visualize simulation results dynamically.

hongyuanjia/eplusr documentation built on Feb. 14, 2024, 5:38 a.m.