Honeybee DesignBuilder

https://www.ladybug.tools/honeybee-designbuilder/docs/
Admin
Honeybee DesignBuilder is an extension for Honeybee that enables the translation, import, and export...
Tokens:41,897
Snippets:234
Trust Score:9.3
Update:2 days ago
Show doc for...
Tokens:
Raw
### sub_face_to_dsbxml_element function (partial)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Starts the definition of a function to convert a honeybee Aperture or Door into an dsbXML Opening element. The code is incomplete as shown.

```python
[docs]
def sub_face_to_dsbxml_element(sub_face, surface_element=None, sub_face_type=None):
    """Generate an dsbXML Opening Element object from a honeybee Aperture or Door.


```

--------------------------------

### host (property)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/honeybee_designbuilder.properties.room.html

Gets the Room object hosting these properties.

```APIDOC
## host (property)

### Description
Gets the Room object hosting these properties.

### Property
host

```

--------------------------------

### RoomDesignBuilderProperties.__init__

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/properties/room.html

Initializes a RoomDesignBuilderProperties object with a host Room and an optional floor geometry.

```APIDOC
## RoomDesignBuilderProperties.__init__

### Description
Initializes a RoomDesignBuilderProperties object with a host Room and an optional floor geometry.

### Method
Constructor

### Signature
`__init__(self, host, floor_geometry=None)`

### Parameters
- **host** (honeybee_core Room) - Required - The Room object that hosts these properties.
- **floor_geometry** (Face3D) - Optional - A horizontal Face3D object used to compute block partitions and perimeters during export to dsbXML. If None, floor geometry is auto-calculated from the 3D Room geometry. Default: None.

### Returns
None
```

--------------------------------

### floor_geometry (property)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/honeybee_designbuilder.properties.room.html

Gets or sets a horizontal Face3D to set the floor geometry.

```APIDOC
## floor_geometry (property)

### Description
Gets or sets a horizontal Face3D to set the floor geometry.

### Property
floor_geometry

```

--------------------------------

### Create room body XML with vertices and surfaces

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Creates the 'Body' XML element for the room, setting volume and extrusion height attributes, adding vertex points, and then adding surface elements. Reverses face indices if the face orientation is opposite to the rebuilt face.

```python
    # create the body of the room using the polyhedral vertices
    hgt = round(room.max.z - room.min.z, 4)
    xml_body = ET.SubElement(
        xml_zone, 'Body', volume=str(room.volume), extrusionHeight=str(hgt))
    _object_ids(xml_body, room.identifier, '0', block_handle)
    xml_vertices = ET.SubElement(xml_body, 'Vertices')
    for pt in room_geometry.vertices:
        xml_point = ET.SubElement(xml_vertices, 'Point3D')
        xml_point.text = '{}; {}; {}'.format(pt.x, pt.y, pt.z)

    # add the surfaces
    xml_faces = ET.SubElement(xml_body, 'Surfaces')
    unique_vertices = room_geometry.vertices
    for face, fi, f_adj in zip(room_faces, room_geometry.face_indices, face_adjs):
        boundary = tuple(unique_vertices[i] for i in fi[0])
        rebuilt_face = Face3D(boundary)
        if face.geometry.plane.n.angle(rebuilt_face.plane.n) > (math.pi / 2):
            # face indices are reversed from Face3D objects
            fi = [list(reversed(pt_i)) for pt_i in fi]
        face_to_dsbxml_element(
            face, xml_body, fi, f_adj, sub_face_type,
            tolerance, angle_tolerance, reset_counter=False
        )
```

--------------------------------

### RoomDesignBuilderProperties.ToString and __repr__ methods

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/properties/room.html

Provides string representations of the properties, with ToString calling __repr__ and __repr__ returning a formatted string with the host's display name.

```python
    def ToString(self):
        return self.__repr__()
```

```python
    def __repr__(self):
        return 'Room DesignBuilder Properties: [host: {}]'.format(self.host.display_name)
```

--------------------------------

### floor_geometry (property)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Gets the floor geometry of the room design builder properties.

```APIDOC
## floor_geometry (property)

### Description
Gets the floor geometry of the room design builder properties.

### Property
floor_geometry

### Applies To
- honeybee_designbuilder.properties.room.RoomDesignBuilderProperties

### Returns
object - The floor geometry.
```

--------------------------------

### RoomDesignBuilderProperties.__init__

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/properties/room.html

Constructor for RoomDesignBuilderProperties. Initializes the object from a dictionary of properties, typically coming from a Model.

```APIDOC
## RoomDesignBuilderProperties.__init__

### Description
Initializes a RoomDesignBuilderProperties object from a dictionary of properties.

### Method
Constructor

### Parameters
- **data** (dict) - Required - A RoomDesignBuilderProperties dictionary (typically coming from a Model).

### Notes
If the dictionary contains a 'floor_geometry' key with a non-None value, the floor_geometry attribute is set to a Face3D object created from the dictionary.
```

--------------------------------

### Define face_to_dsbxml_element function signature

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Starts the definition of a function that generates a dsbXML Surface Element from a honeybee Face, with parameters for zone body element, zone face indices, adjacency faces, sub-face type, tolerance, angle tolerance, and a reset counter.

```python
def face_to_dsbxml_element(
    face, zone_body_element=None, zone_face_indices=None, adjacency_faces=None,
    sub_face_type=None, tolerance=0.001, angle_tolerance=1.0, reset_counter=True
):
    """Generate an dsbXML Surface Element object from a honeybee Face.

    The resulting Element has all constituent geometry (Apertures, Doors).

```

--------------------------------

### ToString and __repr__ methods

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/properties/model.html

ToString returns the string representation of the object. __repr__ returns a formatted string with the host display name.

```python
[docs]
    def ToString(self):
        return self.__repr__()



    def __repr__(self):
        return 'Model DesignBuilder Properties: [host: {}]'.format(self.host.display_name)
```

--------------------------------

### RoomDesignBuilderProperties.from_dict method

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/properties/room.html

Initializes the properties from a dictionary, extracting the 'floor_geometry' key if present and not None, and converting it to a Face3D object.

```python
        Args:
            data: A RoomDesignBuilderProperties dictionary (typically coming from a Model).
        """
        if 'floor_geometry' in data and data['floor_geometry'] is not None:
            self.floor_geometry = Face3D.from_dict(data['floor_geometry'])
```

--------------------------------

### scale() (honeybee_designbuilder.properties.room.RoomDesignBuilderProperties)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Method to scale a room's design builder properties.

```APIDOC
## scale()

### Description
Scales the room's design builder properties.

### Method
scale()

### Parameters
- **factor** (number) - Required - Scaling factor.

### Returns
- **RoomDesignBuilderProperties** - The scaled properties.
```

--------------------------------

### room_to_dsbxml() (in module honeybee_designbuilder.writer)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Function to write a room to DSBXML.

```APIDOC
## room_to_dsbxml()

### Description
Writes a room to DSBXML.

### Method
room_to_dsbxml()

### Parameters
None documented.

### Returns
None documented.
```

--------------------------------

### Add rooms to XML block with label positions

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Creates a 'Zones' subelement under the XML block and iterates over room groups, adding each room as a DSB XML element and setting its label position as a Point3D with semicolon-separated coordinates.

```python
# add the rooms to the block
ET.SubElement(xml_block, 'Zones')
for room, label_pt in zip(room_group, label_pts):
    xml_room = room_to_dsbxml_element(
        room, xml_block, sub_face_type, tolerance, angle_tolerance,
        reset_counter=False
    )
    xml_label = ET.SubElement(xml_room, 'LabelPosition')
    xml_label_pt = ET.SubElement(xml_label, 'Point3D')
    xml_label_pt.text = '{}; {}; {}'.format(label_pt.x, label_pt.y, label_pt.z)
```

--------------------------------

### model_to_dsbxml(model, xml_template='Default', sub_face_type=None, program_name=None)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/honeybee_designbuilder.writer.html

Generates an dsbXML string for a Model, including all geometry, constructions, materials, schedules, room properties, and simulation parameters.

```APIDOC
## model_to_dsbxml(model, xml_template='Default', sub_face_type=None, program_name=None)

### Description
Generate an dsbXML string for a Model. The resulting string will include all geometry (Rooms, Faces, Apertures, Doors, Shades), all fully-detailed constructions + materials, all fully-detailed schedules, and the room properties. It will also include the simulation parameters. Essentially, the string includes everything needed to simulate the model.

### Parameters
- **model** (honeybee Model) - Required - A honeybee Model for which an dsbXML text string will be returned.
- **xml_template** (str) - Optional - Text for the type of template file to be used to write the dsbXML. Different templates contain different amounts of default assembly library data, which may be needed in order to import the dsbXML into older versions of DesignBuilder. However, this data can greatly increase the size of the resulting dsbXML file. Choose from the following options.
  - Default - a minimal file that imports into the latest versions
  - Assembly - the Default plus an AssemblyLibrary with typical objects
  - Full - a large file with all libraries that can be imported to version 7.3
- **sub_face_type** (str) - Optional - Text for a particular type of Honeybee sub-face object to be written as a DesignBuilder Surface. This is useful in cases of modeling radiant ceiling panels or spandrel panels, which have a special sub-Surface object used to represent them in DesignBuilder instead of splitting the parent Face.
- **program_name** (str) - Optional - Text for the name of the program to be used for the model. (Not explicitly described in source, but present as a parameter.)

### Returns
- dsbXML string
```

--------------------------------

### from_dict()

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Creates a RoomDesignBuilderProperties instance from a dictionary.

```APIDOC
## from_dict()

### Description
Creates a RoomDesignBuilderProperties instance from a dictionary.

### Method
from_dict()

### Applies To
- honeybee_designbuilder.properties.room.RoomDesignBuilderProperties

### Parameters
- **data** (dict) - Required - Dictionary containing property values.

### Returns
RoomDesignBuilderProperties - The created instance.
```

--------------------------------

### Usage: Create and write dsbXML string

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/honeybee_designbuilder.writer.html

Shows how to create a Honeybee Model, generate a dsbXML string, and write it to a file using DesignBuilder encoding (ISO-8859-15). Requires an office_program variable to be defined.

```python
import os
from honeybee.model import Model
from honeybee.room import Room
from honeybee.config import folders

# Crate an input Model
room = Room.from_box('Tiny House Zone', 5, 10, 3)
room.properties.energy.program_type = office_program
room.properties.energy.add_default_ideal_air()
model = Model('Tiny House', [room])

# create the dsbXML string for the model
xml_str = model.to.dsbxml(model)

# write the final string into an XML file using DesignBuilder encoding
dsbxml = os.path.join(folders.default_simulation_folder, 'in_dsb.xml')
with open(dsbxml, 'wb') as fp:
    fp.write(xml_str.encode('iso-8859-15'))
```

--------------------------------

### honeybee-designbuilder translate command usage

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/cli/translate.html

Shows the general usage of the translate command with its options and subcommands.

```bash
honeybee-designbuilder translate [OPTIONS] COMMAND [ARGS]...
```

--------------------------------

### honeybee-designbuilder translate model-to-dsbxml command usage

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/cli/translate.html

Shows the usage of the model-to-dsbxml subcommand, which translates a Honeybee Model file to a DsbXML file.

```bash
honeybee-designbuilder translate model-to-dsbxml [OPTIONS] MODEL_FILE
```

--------------------------------

### RoomDesignBuilderProperties.duplicate method

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/properties/room.html

Creates a copy of the properties, optionally with a new host Room object.

```python
    def duplicate(self, new_host=None):
        """Get a copy of this object.

        Args:
            new_host: A new Room object that hosts these properties.
                If None, the properties will be duplicated with the same host.
        """
        _host = new_host or self._host
        new_room = RoomDesignBuilderProperties(_host, self.floor_geometry)
        return new_room
```

--------------------------------

### Create ProfileBody with vertices and surfaces

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Creates a ProfileBody subelement with Body, ObjectIDs, Vertices, and Surfaces. Iterates over faces, rebuilds boundaries, checks face orientation, and calls face_to_dsbxml_element to add each face with adjacency data.

```python
# create the body of the block using the polyhedral vertices
xml_profile = ET.SubElement(
    xml_block, 'ProfileBody', elementSlope='0.0000', roofOverlap='0.0000')
xml_body = ET.SubElement(
    xml_profile, 'Body', volume=str(block_room.volume), extrusionHeight=str(hgt))
_object_ids(xml_body, block_room.identifier, '0', str(block_handle))
xml_vertices = ET.SubElement(xml_body, 'Vertices')
for pt in blk_room.geometry.vertices:
    xml_point = ET.SubElement(xml_vertices, 'Point3D')
    xml_point.text = '{}; {}; {}'.format(pt.x, pt.y, pt.z)
ET.SubElement(xml_body, 'Surfaces')
zip_obj = zip(blk_room.faces, blk_room.geometry.face_indices, face_adjs)
unique_vertices = blk_room.geometry.vertices
for face, fi, f_adj in zip_obj:
    boundary = tuple(unique_vertices[i] for i in fi[0])
    rebuilt_face = Face3D(boundary)
    if face.geometry.plane.n.angle(rebuilt_face.plane.n) > (math.pi / 2):
        # face indices are reversed from Face3D objects
        fi = [list(reversed(pt_i)) for pt_i in fi]
    face_xml = face_to_dsbxml_element(
        face, xml_body, fi, adjacency_faces=f_adj,
        tolerance=tolerance, angle_tolerance=angle_tolerance, reset_counter=False
    )
    face_xml.set('defaultOpenings', 'True')
    face_xml.set('thickness', '0.1')
    f_obj_ids_xml = face_xml.find('ObjectIDs')
    f_obj_ids_xml.set('zoneHandle', '-1')
    f_obj_ids_xml.set('surfaceIndex', '-1')
    adjs_xml = face_xml.find('Adjacencies')
    if f_adj is None:
        f_adj = [face] * len(adjs_xml)
    for adj_xml, af in zip(adjs_xml, f_adj):
        if 'zone_handle' not in af.user_data:
            continue
        adj_xml.set('type', 'Floor')
        in_adj_ids = adj_xml.find('ObjectIDs')
        in_adj_ids.set('handle', '-1')
        in_adj_ids.set('buildingHandle', '-1')
        in_adj_ids.set('buildingBlockHandle', '-1')
        in_adj_ids.set('zoneHandle', af.user_data['zone_handle'])
        in_adj_ids.set('surfaceIndex', af.user_data['surface_index'])
        polys_xml = adj_xml.find('AdjacencyPolygonList')
        for poly_xml in polys_xml:
            out_adj_ids = poly_xml.find('ObjectIDs')
            out_adj_ids.set('handle', '-1')
            out_adj_ids.set('buildingHandle', '-1')
            out_adj_ids.set('buildingBlockHandle', '-1')
            out_adj_ids.set('zoneHandle', '-1')
            out_adj_ids.set('surfaceIndex', '-1')
```

--------------------------------

### duplicate()

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Creates a copy of the room design builder properties.

```APIDOC
## duplicate()

### Description
Creates a copy of the room design builder properties.

### Method
duplicate()

### Applies To
- honeybee_designbuilder.properties.room.RoomDesignBuilderProperties

### Parameters
None

### Returns
RoomDesignBuilderProperties - A duplicate of the current properties.
```

--------------------------------

### shade_to_dsbxml() (in module honeybee_designbuilder.writer)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Converts a shade to DesignBuilder XML.

```APIDOC
## shade_to_dsbxml()

### Description
Converts a shade to DesignBuilder XML.

### Method
shade_to_dsbxml()

### Parameters
- **shade** (object) - Required - The shade to convert.

### Returns
- **str** - The DesignBuilder XML string.
```

--------------------------------

### room_to_dsbxml(room)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/honeybee_designbuilder.writer.html

Generates an dsbXML Zone string object for a honeybee Room. The resulting string contains all constituent geometry (Faces, Apertures, Doors).

```APIDOC
## room_to_dsbxml(room)

### Description
Generates an dsbXML Zone string object for a honeybee Room. The resulting string contains all constituent geometry (Faces, Apertures, Doors).

### Parameters
- **room** (honeybee Room) - Required - A honeybee Room for which an dsbXML Zone string object will be returned.

### Returns
- **str** - An dsbXML Zone string object.
```

--------------------------------

### duplicate(new_host=None)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/honeybee_designbuilder.properties.room.html

Creates a copy of this object, optionally with a new host.

```APIDOC
## duplicate(new_host=None)

### Description
Get a copy of this object.

### Method
`duplicate(new_host=None)`

### Parameters
- **new_host** (Room) - Optional - A new Room object that hosts these properties. If None, the properties will be duplicated with the same host.

### Returns
- **RoomDesignBuilderProperties** - A copy of this object.

```

--------------------------------

### room_to_dsbxml

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Generates a dsbXML Zone string object for a honeybee Room. The resulting string includes all constituent geometry (Faces, Apertures, Doors).

```APIDOC
## room_to_dsbxml

### Description
Generates a dsbXML Zone string object for a honeybee Room. The resulting string includes all constituent geometry (Faces, Apertures, Doors).

### Parameters
- **room** (honeybee Room) - Required - A honeybee Room for which an dsbXML Zone string object will be returned.

### Returns
- **str** - The dsbXML Zone string.
```

--------------------------------

### Module imports and constants for honeybee_designbuilder.writer

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Imports required libraries and defines the DESIGNBUILDER_VERSION constant and a global HANDLE_COUNTER used for generating unique handles.

```python
# coding=utf-8
"""Methods to write Honeybee core objects to dsbXML."""
import os
import math
import datetime
from copy import deepcopy
import xml.etree.ElementTree as ET

from ladybug_geometry.geometry2d import Point2D, Polygon2D
from ladybug_geometry.geometry3d import Vector3D, Point3D, Face3D, Polyface3D
from honeybee.typing import clean_string
from honeybee.aperture import Aperture
from honeybee.face import Face
from honeybee.room import Room
from honeybee.facetype import Floor, RoofCeiling, AirBoundary, face_types
from honeybee.boundarycondition import Outdoors, Surface, Ground, boundary_conditions
from honeybee_energy.boundarycondition import Adiabatic

DESIGNBUILDER_VERSION = '2025.1.0.085'
HANDLE_COUNTER = 1  # counter used to generate unique handles when necessary
```

--------------------------------

### RoomDesignBuilderProperties.move()

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Method of RoomDesignBuilderProperties class that moves the room.

```APIDOC
## RoomDesignBuilderProperties.move()

### Description
Moves the room by a specified vector.

### Module
- `honeybee_designbuilder.properties.room`

### Parameters
- **moving_vec** (Vector3D) - Required - Vector to move the room by.

### Returns
- None
```

--------------------------------

### honeybee-designbuilder-translate-model-to-dsbxml command line option

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Command line interface for translating a Honeybee model to DesignBuilder XML (dsbxml). Includes options for output file, program name, sub-face type, and XML template.

```APIDOC
## honeybee-designbuilder-translate-model-to-dsbxml

### Description
Translates a Honeybee model to DesignBuilder XML (dsbxml) format.

### Usage
honeybee-designbuilder translate model-to-dsbxml [OPTIONS] MODEL_FILE

### Options
- **--output-file, -o** (string) - Path to output file.
- **--program-name, -p** (string) - Program name to use.
- **--sub-face-type, -sf** (string) - Sub-face type to use.
- **--xml-template, -t** (string) - Path to XML template.

### Arguments
- **MODEL_FILE** (string) - Path to the input model file.

```

--------------------------------

### Add internal partitions to XML block

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Creates an 'InternalPartitions' XML element under the block, iterates over internal edges of the floor polyface, finds matching faces with Surface boundary conditions, and writes partition attributes and start/end points. Uses a global HANDLE_COUNTER for unique partition IDs.

```python
    # add internal partitions to the block
    xml_partitions = ET.SubElement(xml_block, 'InternalPartitions')
    part_height = max_z - min_z
    for part_geo in flr_polyface.internal_edges:
        p_min, p_max = part_geo.min, part_geo.max
        p_min = Point2D(p_min.x, p_min.y)
        p_max = Point2D(p_max.x, p_max.y)
        # find the faces associated with the partition
        rel_faces = []
        for room in room_group:
            for face in room:
                f_min, f_max = face.min, face.max
                f_min = Point2D(f_min.x, f_min.y)
                f_max = Point2D(f_max.x, f_max.y)
                if p_min.is_equivalent(f_min, tolerance) and \
                        p_max.is_equivalent(f_max, tolerance):
                    rel_faces.append(face)
        # identify the two faces that coincide with the partition
        match_faces = None
        for i, i_face in enumerate(rel_faces):
            if match_faces is not None:
                break
            if isinstance(i_face.boundary_condition, Surface):
                for o_face in rel_faces[i + 1:]:
                    if isinstance(o_face.boundary_condition, Surface):
                        bc_obj = o_face.boundary_condition.boundary_condition_object
                        if i_face.identifier == bc_obj:
                            match_faces = (i_face, o_face)
                            break
        # create the internal partition object
        if match_faces is not None:
            part_id = str(HANDLE_COUNTER)
            HANDLE_COUNTER += 1
            for face in match_faces:
                if face.user_data is None:
                    face.user_data = {'partition_handle': part_id}
                else:
                    face.user_data['partition_handle'] = part_id
            part_type = 'Virtual' if isinstance(face.type, AirBoundary) else 'Solid'
            part_id_attr = {
                'type': part_type,
                'height': str(part_height),
                'area': str(part_height * part_geo.length),
                'floatingPartition': 'False',
            }
            xml_part = ET.SubElement(xml_partitions, 'InternalPartition', part_id_attr)
            _object_ids(xml_part, part_id, '0', str(block_handle))
            st_pt, end_pt = part_geo.p1, part_geo.p2
            xml_st_pt = ET.SubElement(xml_part, 'StartPoint')
            xml_point = ET.SubElement(xml_st_pt, 'Point3D')
            xml_point.text = '{}; {}; {}'.format(st_pt.x, st_pt.y, st_pt.z)
            xml_end_pt = ET.SubElement(xml_part, 'EndPoint')
            xml_point = ET.SubElement(xml_end_pt, 'Point3D')
            xml_point.text = '{}; {}; {}'.format(end_pt.x, end_pt.y, end_pt.z)
```

--------------------------------

### Write dsbXML file from honeybee Model

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Writes a dsbXML file from a honeybee Model. Creates the output directory if needed, encodes the XML string in ISO-8859-15, and returns the output file path.

```python
    # make sure the directory exists where the file will be written
    dir_name = os.path.dirname(os.path.abspath(output_file))
    if not os.path.isdir(dir_name):
        os.makedirs(dir_name)
    # get the string of the dsbXML file
    xml_str = model_to_dsbxml(model, xml_template, sub_face_type, program_name)
    # write the string into the file and encode it in ISO-8859-15
    with open(output_file, 'wb') as fp:
        fp.write(xml_str.encode('iso-8859-15', errors='ignore'))
    return output_file
```

--------------------------------

### room_to_dsbxml_element() (in module honeybee_designbuilder.writer)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Function to write a room to a DSBXML element.

```APIDOC
## room_to_dsbxml_element()

### Description
Writes a room to a DSBXML element.

### Method
room_to_dsbxml_element()

### Parameters
None documented.

### Returns
None documented.
```

--------------------------------

### Join flat floors to determine internal partitions

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Builds polygons from floor geometries, including holes, and optionally removes colinear vertices and intersects polygon segments when any room lacks a designbuilder floor_geometry. Creates Face3D objects and a Polyface3D to extract internal edges.

```python
    # join the flat floors of the rooms together to determine internal partitions
    polygons, is_holes = [], []
    for f_geo in floor_geos:
        is_holes.append(False)
        b_poly = Polygon2D(tuple(Point2D(pt.x, pt.y) for pt in f_geo.boundary))
        polygons.append(b_poly)
        if f_geo.has_holes:
            for hole in f_geo.holes:
                is_holes.append(True)
                h_poly = Polygon2D(tuple(Point2D(pt.x, pt.y) for pt in hole))
                polygons.append(h_poly)
    if any(r.properties.designbuilder.floor_geometry is None for r in room_group):
        polygons = [poly.remove_colinear_vertices(tolerance) for poly in polygons]
        polygons = Polygon2D.intersect_polygon_segments(polygons, tolerance)
    face_pts, flat_flr_geos = [], []
    for poly, is_hole in zip(polygons, is_holes):
        pt_3d = [Point3D(pt.x, pt.y, min_z) for pt in poly]
        if not is_hole:
            face_pts.append((pt_3d, []))
        else:
            face_pts[-1][1].append(pt_3d)
    for f_pts in face_pts:
        flat_flr_geos.append(Face3D(f_pts[0], holes=f_pts[1]))
    flr_polyface = Polyface3D.from_faces(flat_flr_geos, tolerance)
```

--------------------------------

### room_to_dsbxml_element function signature

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Function signature for generating a dsbXML Zone Element from a honeybee Room. Parameters include room, block_element, sub_face_type, tolerance, angle_tolerance, and reset_counter.

```python
def room_to_dsbxml_element(
    room, block_element=None, sub_face_type=None,
    tolerance=0.001, angle_tolerance=1.0, reset_counter=True
):
    """Generate an dsbXML Zone Element object for a honeybee Room."""
```

--------------------------------

### ToString()

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Returns a string representation of the properties object. Available on ModelDesignBuilderProperties and RoomDesignBuilderProperties.

```APIDOC
## ToString()

### Description
Returns a string representation of the properties object.

### Method
`ToString()`

### Applies to
- `honeybee_designbuilder.properties.model.ModelDesignBuilderProperties`
- `honeybee_designbuilder.properties.room.RoomDesignBuilderProperties`

### Returns
- `str` - A string representation of the properties object.
```

--------------------------------

### reflect() (honeybee_designbuilder.properties.room.RoomDesignBuilderProperties method)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Method to reflect a room's geometry.

```APIDOC
## reflect()

### Description
Reflects the room's geometry.

### Method
reflect()

### Parameters
None documented.

### Returns
None documented.
```

--------------------------------

### face_to_dsbxml()

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Converts a face to DSBXML format.

```APIDOC
## face_to_dsbxml()

### Description
Converts a face to DSBXML format.

### Method
face_to_dsbxml()

### Module
honeybee_designbuilder.writer

### Parameters
- **face** (object) - Required - The face object to convert.

### Returns
str - DSBXML representation of the face.
```

--------------------------------

### face_to_dsbxml(face)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/honeybee_designbuilder.writer.html

Generates an dsbXML Surface string from a honeybee Face, including all constituent geometry (Apertures, Doors).

```APIDOC
## face_to_dsbxml(face)

### Description
Generate an dsbXML Surface string from a honeybee Face. The resulting string has all constituent geometry (Apertures, Doors).

### Parameters
- **face** (honeybee Face) - Required - A honeybee Face for which an dsbXML Surface string object will be returned.

### Returns
- dsbXML Surface string
```

--------------------------------

### sub_face_to_dsbxml() (in module honeybee_designbuilder.writer)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/genindex.html

Converts a sub-face to DesignBuilder XML.

```APIDOC
## sub_face_to_dsbxml()

### Description
Converts a sub-face to DesignBuilder XML.

### Method
sub_face_to_dsbxml()

### Parameters
- **sub_face** (object) - Required - The sub-face to convert.

### Returns
- **str** - The DesignBuilder XML string.
```

--------------------------------

### apply_properties_from_dict method

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/properties/model.html

Applies the energy properties from a dictionary to the host Model. Requires the dictionary to have ModelDesignBuilderProperties. Iterates over rooms and applies designbuilder properties to each room.

```python
[docs]
    def apply_properties_from_dict(self, data):
        """Apply the energy properties of a dictionary to the host Model of this object.

        Args:
            data: A dictionary representation of an entire honeybee-core Model.
                Note that this dictionary must have ModelEnergyProperties in order
                for this method to successfully apply the energy properties.
        """
        assert 'designbuilder' in data['properties'], \
            'Dictionary possesses no ModelDesignBuilderProperties.'
        room_dsb_dicts = []
        if 'rooms' in data and data['rooms'] is not None:
            for room_dict in data['rooms']:
                try:
                    room_dsb_dicts.append(room_dict['properties']['designbuilder'])
                except KeyError:
                    room_dsb_dicts.append(None)
            for room, r_dict in zip(self.host.rooms, room_dsb_dicts):
                if r_dict is not None:
                    room.properties.designbuilder.apply_properties_from_dict(r_dict)
```

--------------------------------

### Process block room faces for body formatting

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Iterates over the block room's faces, matches them to room group faces by identifier, stores zone handle and surface index in user_data, removes sub-faces, and assigns a new identifier from HANDLE_COUNTER. Prints a warning if a face fails to match.

```python
# process the faces of the block room to be formatted for a body
for f in block_room.faces:
    face_matched = False
    for room in room_group:
        for f2 in room:
            if f.identifier == f2.identifier:
                f.user_data = {
                    'zone_handle': room.identifier,
                    'surface_index': f2.user_data['dsb_face_i']
                }
                face_matched = True
                break
        if face_matched:
            break
    else:
        print('Failed to match the block Face: {}'.format(f.display_name))
    f.remove_sub_faces()
    f.identifier = str(HANDLE_COUNTER)
    HANDLE_COUNTER += 1
```

--------------------------------

### sub_face_to_dsbxml(sub_face)

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/honeybee_designbuilder.writer.html

Generates an dsbXML Opening string from a honeybee Aperture or Door.

```APIDOC
## sub_face_to_dsbxml(sub_face)

### Description
Generate an dsbXML Opening string from a honeybee Aperture or Door.

### Parameters
- **sub_face** – A honeybee Aperture or Door for which an dsbXML Opening XML string will be returned.

### Returns
- dsbXML Opening XML string.
```

--------------------------------

### Create DesignBuilder Zone Element from Honeybee Room

Source: https://www.ladybug.tools/honeybee-designbuilder/docs/_modules/honeybee_designbuilder/writer.html

Converts a honeybee Room into a DesignBuilder XML Zone element. Handles optional BuildingBlock element, sub-face types, and rebuilds faces with holes. Uses global HANDLE_COUNTER and tolerance parameters.

```python
    global HANDLE_COUNTER  # declare that we will edit the global variable
    # create the zone element
    is_extrusion = room.is_extrusion(tolerance, angle_tolerance)
    zone_id_attr = {
        'parentZoneHandle': room.identifier,
        'inheritedZoneHandle': room.identifier,
        'planExtrusion': str(is_extrusion),
        'innerSurfaceMode': 'Approximate'  # TODO: eventually change to deflation
    }
    if block_element is not None:
        block_zones_element = block_element.find('Zones')
        xml_zone = ET.SubElement(block_zones_element, 'Zone', zone_id_attr)
        obj_ids = block_element.find('ObjectIDs')
        block_handle = obj_ids.get('handle')
    else:
        xml_zone = ET.Element('Zone', zone_id_attr)
        block_handle = '-1'

    # rebuild the faces with holes if any are found
    if any(f.geometry.has_holes for f in room.faces):
        rebuilt_face_3ds = []
        for face in room.faces:
            if face.geometry.has_holes:
                flat_pt_face = Face3D(
                    face.geometry.vertices, plane=face.geometry.plane
                )
                rebuilt_face = flat_pt_face.separate_boundary_and_holes(tolerance)
                face._geometry = rebuilt_face
                rebuilt_face_3ds.append(rebuilt_face)
            else:
                rebuilt_face_3ds.append(face.geometry)
        room._geometry = Polyface3D.from_faces(rebuilt_face_3ds, tolerance)
        if not room._geometry.is_solid:
            room._geometry = room._geometry.merge_overlapping_edges(tolerance)
```
Tokens:
Raw