4.1. buildes Package

Initialization for buildes program

Provides intialization resources for buildes.

This is a description of what the following modules do. This information is important to understand the structure and relationship between the various parts of buildes. NOTE: There is a similar overview for all packages.

• buildes
• buildesui
• buildesapp
• buildesdata

---

The buildes module provides the user-visible functions the user uses to achieve the capability provided in the buildes program.

4.1.1. bdui Module

Buildes GUI

Provides a window for working with Buildes.

I used the book ‘Rapid GUI Programming with Python and Qt : the definitive guide to PyQt programming’ by Mark Summerfield from [Prentice Hall] as the definitive reference. Of course the complete project would not be possible without specific customization references provided over the internet by numerous others. I tried to give credit in the specific areas in code wherever I could.

class bdui.BuildesGUI(*args)

Bases: PyQt4.QtGui.QMainWindow

Provides tools to view and receive information while using buildes

PaintPageView(printer)

about1Action()

Show information about Buildes.

about2Action()

Show information about Buildes GUI.

addActions(target, actions)

Helper for adding actions to menu or toolbar.

Parameters:

• target –
• actions –

addRecentFile(fname)

Adds recently used session files to file menu list.

Parameter:fname (String) – name of file that have been recently opened.

addToGroup(levelList, oType)

Populate the provided group type with the appropriate objects.

Parameters:

• markList –
• oType –

addToLevels(objType, levelList)

Populate the tree of levels with named objects.

Parameters:

• objType (String) – Name of object to be added to tree of levels
• levelList (List) – All level names in the design

addToSpaces(levelList, oType)

Populate the tree of spaces with their parts and bounds.

Spaces have sides which are part of them. They also have other components such as furniture and fixtures which they bound. All these should be the children of the specific space in the tree. The parts of the space are added first followed by the bounded objects.

appExit()

Exit buildesUi

It first determines if user really wants to exit. If this is true it then saves the last opened file as well as the recent list of files. It also saves the state of the application including size and position of the windows before closing.

arcmarkTPL()

Insert a arcMark object in text area

arcopenTPL()

Insert a arcOpen object in text area

arcsideTPL()

Insert a arcSide object in text area

azure3Background()

Set modelTab background color to azure3.

bottomView()

Create single bottom model view.

cEOffsetTPL()

Insert a connect-from-edge offset directive in text area

cOffsetTPL()

Insert a connect-from-snap offset directive in text area

checkFilePath(filePath)

Return true if path is to an accessible file.

Parameter:filePath (String) – Absolute path to an existing file Returns:Whether filePath exists Return type:Boolean

circlemarkTPL()

Insert a circleMark object in text area

circleopenTPL()

Insert a circleOpen object in text area

circlesideTPL()

Insert a circleSide object in text area

cleanEditor()

Wipes all text in the editor

clearQueryLine(string)

Testing testing

Parameter:string –

colorTPL()

Insert a color directive in text area

createAction(text, slot=None, shortcut=None, tip=None, icon=None, checkable=False, signal=u'triggered()')

Helper for creating actions to be performed in menus and toolbars.

Parameters:

• text (String) – Name for action
• slot (Method) – Function name to perform the action
• shortcut (QtGui.QKeySequence) – Key sequence to initiate action
• icon (Image) – Image to associate to action
• tip (String) – Tooltip and status message
• checkable (Boolean) – Whether action is a switch
• signal (QtCore.SIGNAL) – For connecting the slot

Returns:

Menu action

Return type:

QtGui.QAction

eOffsetTPL()

Insert an edge offset directive in text area

editRedo()

Redo the last action in text area

editUndo()

Undo last action in text Area

exactHLR()

Create an exact High ... in modelTab

fOffsetTPL()

Insert a fit offset directive in text area

fileClose()

Close the current file.

fileNew()

Start a new session file.

fileOpen()

Open a session file.

fileOutline()

Insert session file outline in text area

filePrint()

Print a session file.

fileSave()

Save a session file.

fileSaveAs()

Save a session file by entering a file name.

findRepText()

Find and replace text in editor

fitView()

Center the current single model view.

frontView()

Create single front model view.

gOffsetTPL()

Insert a global offset directive in text area

getObjInfo(name)

Returns formated data about named object.

Parameter:name (QString) – Name of object Returns:Formated string of data Return type:String

getRootPath(fileName)

Returns the root path to filename

Parameter:fileName (String) – Desired file name Returns:Combines fileName to expected path under root installation Return type:String

getSiteList()

Returns name and contents of site object.

Returns:A list of names. Return type:List

getUserPath(fileName)

Returns the user path to filename

Parameter:fileName (String) – Desired file name Returns:Combines fileName to expected path under user directory Return type:String

get_msgnum()

Get buildes static message number

gray20Background()

Set modelTab background color to gray20.

gray30Background()

Set modelTab background color to gray30.

gray95Background()

Set modelTab background color to gray95.

groupTPL()

Insert a group object in text area

helpAction()

Show help information.

helpTPL()

Show help on using templates

infoRef()

Check and render model in modelview

Checks if it is OK to render model in modelView then proceed or abort accordingly

infoRefresh()

Processes the saved session file to display building information.

initActions()

Initializes actions that can be performed.

This is called by __init__ to setup and connect actions to be provided in the menubar and toolbar. It sets up the actions by calling createAction. This is a helper method just to help minimize the steps or number of lines required in creating these actions. Another helper method called addActions is then used to actually add the actions to each menu or toolbar. Note that the filemenu is different because we want to refresh the file menu frequently to show the list of nine last opened files. We save the filemenu actions in a tuple called fileMenuActions, then we connect the filemenu to the slot updateFileMenu to be performed whenever the user clicks on the menu which emits the aboutToShow signal.

insertFile(fileName, clean=False)

Inserts named file into editor. If clear, it clear editor first

Parameters:

• fileName (String) – Absolute path and fileName to resource
• clear (Boolean) – Flag to determine whether to clear contents of editor

insertTpl(tplFile)

Insert the provided template at cursor position in gui

Parameter:tplFile (String) – Absolute path and file name of template

leftView()

Create single left model view.

levelTPL()

Insert a site object in text area

linemarkTPL()

Insert a lineMark object in text area

lineopenTPL()

Insert a lineOpen object in text area

linesideTPL()

Insert a lineSide object in text area

loadFile(fname=None)

Load a file into the textArea.

There are two parts to this function.

The first part is when a call is made without any file name such as when called from a recently used file action. In such a case we retrieve the sending object which should be a QAction object then we extracts the action’s user data in which we store the file name including path.

In the second part we have a file name which we then try to load.

Parameter:fname (String) – Possible file to be loaded

loadInitialFile()

Load the last file opened.

materialTPL()

Insert a material directive in text area

modelViewResize()

Testing to handle resize events

msgNum

Get buildes static message number

numberLevels(levelList)

Place levels in proper sequence.

Parameter:levelList – Returns:Sorted list of level names. Return type:List

oView()

Create an orthogonal single model view.

okToContinue()

Allows the choice to save or ignore changes.

Checks to determine if there are any changes to session. If ‘Yes’ allows user to save, if No, does not allow to save but changes will be lost, if ‘Cancel’, does not allow changes to be saved but changes can be saved later.

‘Cancel’ brings up the dialog again as this function is called twice. Provided fixes for the rest. BUG, I say!!!!!

Returns:Returns boolean depending on user selection. Return type:Boolean

pView()

Create a perspective single model view.

pageView()

Present a printed preview of text area

pointmarkTPL()

Insert a pointMark object in text area

processQueryLine()

Process the entry in the query line.

queryExplode(string)

Extract function and parameter from user entry in queryLine

queryLineDown()

Reaction to user using the down-arrow button in the query line

Allows the user to forwardly navigate historic items for query line

queryLineUp()

Reaction to user using the up-arrow button in the query line

Allows the user to backwardly navigate historic items for query line

rOffsetTPL()

Insert a relative offset directive in text area

rearView()

Create single rear model view.

removeTrailingSpaces()

TODO: Removes trailing spaces from text in the editor

Returns: Return type:

rightView()

Create single right model view.

selectMsgArea()

Set focus to the msgArea of the GUI

selectQueryLine()

Set focus to the queryLine of the GUI

selectTextArea()

Set focus to the textArea of the GUI

sessProc()

Check and process text in textArea

Checks if it is OK to process text in textArea then proceed or abort accordingly

sessionProcess()

Processes the current session file to compile building information.

sessionSelect()

Allows user to select a Buildes knowledge file.

setKnowledgeFileName()

Set the processed Buildes knowledge file name.

set_msgnum(value)

Set buildes static message number

setupQueryLine()

Sets up a query command line feature

shaded()

Create a shaded view in modelTab

sharesideTPL()

Insert a share side object in text area

showCopyright()

Show copyright in message window.

This happens on first execution of buildesUi only.

showMessage(msg)

Append msg to the message area

Parameter:msg –

showObjInfo(item, column)

Show object information when selected in tree.

Parameters:

• item –
• column –

showProjectInfo(name)

Get project summary data and designer name.

Parameter:name (String) – Site object name.

spaceTPL()

Insert a space object in text area

topView()

Create single top model view.

updateFileMenu()

Populate the filemenu showing any recently opened files.

Rebuilds the filemenu in order to show the list of nine most recently opened filenames.

updateUi(arg=None)

Enables and disables actions in response to program state.

Parameter:arg –

viewerState()

Turn BuildesGUI into a viewer only.

windowView()

Zoom to a window in model view.

wireFrame()

Create a wire frame view in modelTab

4.1.2. buildes Module

4.1.3. buildesapp Module

Buildes module

Manages all objects in a building design created using the Buildes program.

moduleauthor:Kene Meniru <Kene.Meniru@illom.org>

class buildesapp.Buildes

Bases: object

Provides the main boundary class for the Buildes program. This can be considered the application object. It provides access to all components.

assign_color(obj, col=None, mat=None)

Assign color to an object.

Parameters:

• obj –
• col –

assign_material(obj, mat, col=None)

Assign material to an object.

Parameters:

• obj –
• mat –
• col –

buildes_exception(msg)

Raises a custom exception with message.

Parameter:msg –

concat_log_func(funcName, msg)

Combines log message and function name with appropriate delimeter

Parameters:

• funcName (String) – Name of function where message is generated
• msg (String) – Message to be logged

Returns:

Properly combined function name and message

Return type:

String

coord_sys

Set _coord_sys variable

create_site()

Creates the site object.

When buildes startes, it automatically creates a default site object. It does this because every building must have a site and it saves the designer the trouble of having to create one. This default site however, can be replaced by the user’s customized site if manually created. In such cases, the default version is simply replaced. Default site also comes with a default level. This makes it possible for the user to start placing objects if it is a single story building without attention to site parameters.

critical(msg)

Raises a custom exception with message.

Parameter:msg –

debug(msg, func=None)

Provides the ability to count debug log types

Parameter:msg –

edge_labels(edge)

Returns the begin, middle and end labels for an edge.

If edge is None, the default edge letter for components is returned.

Parameter:edge (String) – The desired edge letter Returns:The three snap labels for edge. Return type:None | [String, String, String]

error(msg)

Raises a custom exception with message.

Parameter:msg –

exit()

Stop all processing and exits the program.

get_coord_sys()

Set _coord_sys variable

get_marker_size()

Get size for markers

in_process_add(oname, otype)

Adds an objects name in in_process.

Parameters:

• oname –
• otype –

in_process_check(oname, otype)

Determine if any object of otype is under construction.

For certain objects it is important to monitor their construction process because it is expected that the designer will provide additional parts in successive runs of Buildes. This routine checks to determine if there are other objects of the same type designating that they are still unfinished or under contruction. If there are, it issues a reminder message. If there are none it does not issue any message.

In addition, it adds oname provided to designate that it is now under construction.

Parameters:

• oname (String) – Name of object to check for that is unfinished.
• otype (String) – Type of object to check if unfinished

Returns:

Whether an unfinished object was found.

Return type:

Boolean

in_process_del(oname, otype)

Deletes an object name from inProcess

Parameters:

• oname –
• otype –

in_process_find(otype)

Returns object of otype that is unfinished in the design.

Parameter:otype (String) – Type of object to find that is unfinished. Returns:Name of object that is unfinished in the design. Return type:String

info(msg, func=None)

Provides the ability to count info log types

Parameter:msg –

is_possible_edge(arg)

Check if arg is a possible edge.

Parameter:arg (String) – Possible edge designation. Returns:Whether arg is a possible edge. Return type:Boolean

is_possible_snap(arg)

Check if arg is a possible snap.

Note

Snap is implied if none is provided in arg. For such cases the origin is assumed. In such cases this function should not be used to determine for possible snap.

Parameter:arg (String) – Possible snap designation. Returns:Whether object is a possible snap designation. Return type:Boolean

line_info(msg)

Provide information to enrich messages.

This adds class, method and line information based on the location from where it is called.

Adapted from: http://www.karoltomala.com/blog/?p=720

Parameter:msg (String) – Message the user desires to send out. Returns:Message appended with information to locate where generated Return type:String

make_shapes()

Buildes the shape of all required objects.

marker_size

Get size for markers

other_edge_label(label=None)

Finds snap labels corresponding to other edges of a component.

For example in the above figure, if label provided is a1, [l1, r1] is returned. If label provided is l1, [r1, a1] is returned and finally if label r1 is provided, [l1, a1] is returned. NOTE: The ‘l’ or ‘r’ labels are always the first in the list. This can only be used for objects with width or thickness.

Parameter:label (String) – Label designating the edge in question. Returns:The corresponding labels at the edge of a component. Return type:None | [String, String]

other_end_label(label=None)

Finds the snap label at other end corresponding to label.

For example in the above figure, if label provided is l3, l1 is returned. This can only be used with space sides.

Parameter:label (String) – Label designating the end in question. Returns:Label at the other end of the end in question. Return type:None | String

relate(data_obj, del_name=None)

Facilitates the heirachical relationship necessary in buildings.

Parameters:

• data_obj (object) – Object to be contained in another.
• del_name (String) – Object name to be removed from parent bound list.

remake_data(data)

Remake a data object when main properties were not provided by user.

This is necessary after moving objects using fit_offset and conn_offset.

Parameter:data (BuildesData) – Data object that needs snaps recalculated

save_format_ext(name)

Returns the extension file name for name.

Parameter:name – Returns:Extension file name for name Return type:String

save_format_name(ext)

Returns the extension file ext for ext.

Parameter:ext – Returns:Extension file ext for ext Return type:String

seen_open_side_add(name)

Add an object name to the seen_open_sides list.

Parameter:name (String) – Object name that is or has openSides.

set_color(col=None)

Designate the current selected color object.

Parameter:col –

set_coord_sys(sys)

Get _coord_sys variable

set_direction(obj)

Set orientation in the object provided.

Parameter:obj (BuildesData) – Buildes data object

set_level(name=None)

Change building level.

Parameter:name (String) – Name of level designated by the user. Returns:Whether level change was successful Return type:Boolean

set_marker_size(size)

Set size for markers

set_material(mat=None)

Designate the current selected material object.

Parameter:mat –

setup()

Setup Buildes class members.

setup_log()

Allows the ability to log messages

Sets up loggers to both file (.log) and to stdout. Logs at level of info are sent to the file while those at the level of warn and higher logs are sent to stdout by default.

setup_session_info(path_name, path, name)

Set up name for logging project information

Parameter:path_name – Returns: Return type:

skip(oname, pname)

Determine whether to skip object oname with parent pname.

Parameters:

• oname (String) – Name of object with shape to be skipped
• pname (String) – Name of parent for oname

Returns:

Whether oname is in list of objects in skip_shapes

Return type:

Boolean

skip_add(oname, pname)

Adds an object name in skip_shapes.

Parameters:

• oname (String) – Object name to be skipped
• pname (String) – Parent name of object to be skipped

update_parent_edge(obj)

Allows parents to make any updates to their edges.

Parameter:obj (BuildesData) – Child object.

warn(msg, func=None)

Provides the ability to count warn log types

Parameter:msg –

4.1.4. buildesdata Module

Buildes Data Object

This provides the common object between all buildes data objects.

moduleauthor:Kene Meniru <Kene.Meniru@illom.org>

class buildesdata.BuildesData

Bases: object

Provides the common parameters for data objects in buildes.

arc_side

Get side on which arc will be created

base_elev

Get float for base boundary location

clear_coords()

Remove all saved coordinates.

color

Get the color for object data.

Returns:Color name for object data. Return type:String

exit()

Stops execution in the data object.

finish_bounds()

Finalizes the creation of boundary objects.

get_arc_side()

Get side on which arc will be created

get_base_elev()

Get float for base boundary location

get_color()

Get the color for object data.

Returns:Color name for object data. Return type:String

get_location()

Get object location vectors

get_material()

Get the material name for object.

Returns:Material name for object data. Return type:String

get_top_elev()

Get float for top boundary location

global_snap(label=None)

Retrieves global coordinates for specified or first label.

This is the coordinates at the label after factoring in the global location of the object. Typically all object in Buildes are created around the origin and later moved to the actual location in the design. This routine returns the location after the object has been moved. If the object has not been moved, using this routine is the same as using ‘snap’.

Parameters:

• label (String) – Label designating the point for object.
• typ (String) – Whether to retrieve original or modified coordinates.

Returns:

2D global coordinates at the specified label.

Return type:

Error message | Vector

has(name)

Check if named component is in the site’s _component_list.

Parameter:name (String) – Component object’s name. Returns:Whether name is the list or not. Return type:Boolean

material

Get the material name for object.

Returns:Material name for object data. Return type:String

pos

Get object location vectors

regen_snaps(point, regen_type)

Updates coords relative to the point.

Adjust snaps for moving object

When the coordinates that are not at the origin of an object are used to manipulate the object, it is important to reposition all other coordinates so the object can be moved precisely. When manipulating without rotation, the precision move point is subtracted as described below. When a rotation is needed the move point must be added for rotation to be accurate.

To adjust coordinates for line component at ‘A’ so that it can be moved precisely using point at ‘r2’, it must be repositioned at ‘B’ with ‘r2’ at the origin. All other coordinates must then be regenerated relatively.

Parameters:

• point (Vector) – Point to be adjusted for moving object with.
• coords (Dict) – Dictionary of 2D vectors and their labels.
• regen_type (String) – Type of regeneration needed.

Returns:

Adjusted dictionary of 2D vectors and their labels.

Return type:

Dict

set_arc_side(value)

Set side on which arc will be created

The letter ‘r’ or ‘l’ can be used but need to store these as ‘right’ or ‘left’ in the object.

set_base_elev(value)

Set float for base boundary position

set_color(col)

Set the color for object data.

Parameter:col (ColorData) – Color data for object

set_location(value)

Set object location vectors

set_material(mat)

Set the material object for data object.

Parameter:mat (MaterialData) – Material object for object data.

set_top_elev(value)

Set float for top boundary location

snap(label=None)

Retrieves coordinates for specified or first label.

Parameter:label (String) – Label designating the point for object. Returns:2D coordinates at the specified label. Return type:Error message | Vector

snap_hor_placement(snap)

Return the relative horizontal placement of snap point.

Parameter:snap – Returns:Horizontal position as ‘left’, ‘right’ or ‘none’. Return type:String

snap_id(snap)

Return the label of the provided snap point.

Parameter:snap (Vector) – 2D coordinates for snap point Returns:label of the provided snap point. Return type:None | String

snap_ver_placement(snap)

Return the relative vertical placement of snap point.

This is different compared to kobldes. In kobldes, if this routine returns “bottom”, it means that the vector is actually highest relative to other coords. The aim in kobldes is to designate the direction of the length of wall. This is confusing so I have changed it here. Now the return means exactly what it says. If “down” is returned, this means that the snap is at the bottom relative to other snaps.

Parameter:snap – Returns:Vertical position as ‘up’, ‘down’ or ‘none’. Return type:String

top_elev

Get float for top boundary location

update_bound(new_name, old_name=None)

Add and/or remove objects in the bound_list

bound_list contains names of all objects that define the boundary of another. For example a space object is bounded by side/wall objects.

Parameters:

• new_name (String) – New object name for the list.
• old_name (String) – Old object name already in list.

update_coords(new_name, new_coord, old_name=None)

Add or replace a coordinate in coords.

Coords are updated when component objects are placed in the design. If new_name is different from old_name, then old_name is replaced by new_name. If new_name is the same as old_name, then old_name is updated by new_name.

Parameters:

• new_name (String) – New id for a new coordinate.
• new_coord (Vector) – New coordinate in profile.
• old_name (String) – Existing coordinate id in coords

update_parts(new_name, old_name=None)

Add and/or remove objects in _component_list

_component_list contains names of all objects that are part of an object. For example a table can be part of a space object.

Parameters:

• new_name (String) – New object name for the list.
• old_name (String) – Old object name already in list.

4.1.5. buildesmanager Module

Buildes Manager

Manages the configuration and creation of BuildesData objects.

moduleauthor:Kene Meniru <Kene.Meniru@illom.org>

class buildesmanager.BuildesManager(app)

Bases: object

Coordinates the creation of BuildesData objects.

define_corner(edge)

Update parent edge with edge data.

Parameter:edge (BuildesData) – Reference to edge object.

end_active_status(name=None)

End an object’s active status.

Parameter:name –

get_direction(data)

Establish orientation for object.

Parameter:data –

make_common_data(data)

Set all common attributes for all similar objects.

Parameter:data –

make_message(data=None)

Make introductory message for data object for diplay in the ui.

Parameter:data (BuildesData) – Reference to the data object.

make_profile(data)

Calculate coordinates for defining the data object.

This is where the snaps are created and stored for manipulating and creating the shape of the data object.

Parameter:data –

make_shape(data)

Make a PythonOCC shape for the data object.

Parameter:data (BuildesData) – Reference to the data object.

prep_data(data)

Prepares parts of the data object for use in creation.

Put here any calculations or other activity that may occur before and after the object has been placed in the design using offset. For example see objects that are remade after being placed using fit_offset or conn_offset.

Parameter:data (BuildesData) – Object to be prepared.

summary_id(obj)

Summarized identification message.

Parameter:obj (BuildesData) – Object for which to create summary message. Returns:Formatted text for predetermined cells in the spreadsheet Return type:SpreadSheet

summary_outlook(obj)

Summarized outlook message.

Parameter:obj (BuildesData) – Object for which to create summary message. Returns:Formatted text for predetermined cells in the spreadsheet Return type:SpreadSheet