Export Text using MicroStation Python

Q How do I export Text Elements using MicroStation Python? I want to write a CSV or, preferably, Excel file showing text and coordinates.

A Here's a small Python program that harvests text elements and writes data to an external file. It uses Python pandas to create an Excel file of text element coordinates and text content.

Text Round-Trip

We occasionally read a post on Be Communities: MicroStation Forum about round-tripping text between MicroStation and Excel. By 'round-tripping' we mean …

1. Export text from a MicroStation DGN file to Excel
2. Modify the text in Excel
3. Import text from Excel to MicroStation, replacing existing text

You can use Python projects Export Text and Import Text or Replace Text as the foundation of such a round-tripping application.

Caveat

This project does little else than existing MicroStation tools XYZ Text and Reports. However, those tools don't teach you anything about Python, which is the purpose of this article. Going beyond Python, it introduces pandas: the key to writing an Excel file in just a few lines of code.

Python Implementation

The Export Text Elements example borrows from Python articles and examples delivered with MicroStation Python.

We get a list of DGN elements (as elementRef) in a DGN model using DgnModel.GetGraphicElements(). Next we enumerate the list and analyse each elementRef. In this example, we filter the list by element type (e.g. MicroStation classes TextHandler, TextNodeHandler etc) …

• For each element
  • Create an ElementHandle
  • Extract the DGN element handler with ElementHandle.GetHandler()
  • Test the element handler class to determine if it's a text element or a container
    • If a text element, get its text content
    • If a container, enumerate its children to find embedded text

Function DescribeTextSource() in la_solutions_match_with_class.py analyses an element to differentiate between text, text node and cell elements. See Class Selector.

Element Handlers

Export Text Elements filters the element list by examining the element's handler. Element handlers are classes in MicroStation Python that provide type-specific methods. For example, you can use a TextHandler to create a DGN text element.

HarvestPointElements

This function builds a Python list of PointElementInfo. This project, and some others, make use of a PointElementInfo class. It's described here.

Function HarvestPointElements filters the element list by examining the element's handler. It checks the element class against TextHandler, TextNodeHandler and NormalCellHeaderHandler then creates an ElementHandle.

It tests to see if the ElementHandle has children, which is the case if the element is a text node or cell. If so, it enumerates the children, which are text elements in the case of a text node.

With each text element it calls GetPointElementInfo() to construct a PointElementInfo object, then appends that to a list of PointElementInfo.

It returns the list of PointElementInfo.

ExportPointElements

Function ExtractPointInfoToExcel uses pandas to create an Excel file from the list of PointElementInfo.

We need a file name to create the exported data. In this example, the Excel file is named after the active DGN file, and the sheet is named after the DGN model. We get the DGN file name and model name using Python like this …

    dgnFile = ISessionMgr.ActiveDgnFile
    fileName = dgnFile.GetFileName()
    modelName = ISessionMgr.ActiveDgnModelRef.GetDgnModel().GetModelName()

Get the destination folder using function GetReportFolder(). That extracts the folder name from a MicroStation configuration variable.

    # Initialize a Pandas DataFrame to store data
    df = pd.DataFrame(pointInfo, columns=PointElementInfo.ColumnNames())
    # If this is the first instance, create an empty DataFrame with the column names
    if df.empty:
        df = pd.DataFrame(columns=PointElementInfo.ColumnNames())

    sheetLabel = CreateExcelSheetName("DGN Model", modelName)

Function CreateExcelSheetName is a helper class to work around the restrictions in an Excel sheet name.

The exported file is created in Excel format. If you use Excel to open that file, you'll see something like this …

The Python source code of Export Text Elements is available for download.

Folder Structure

There's a description of our Python project folder structure.

Usage

Export Text Elements is intended to be run from MicroStation's Python Manager.

Unpack the ZIP file and copy the Python file into a folder that MicroStation knows about.

Use MicroStation's Python Manager to find and execute the script.

Questions

Post questions about MicroStation programming to the MicroStation Programming Forum.