MicroStation Element Ranges

Each and every graphical element in a MicroStation DGN file has a range. An element's range is a bounding cube (in 3D) or bounding rectangle (in 2D). The element graphics fits entirely within the range. A MicroStation user normally does not have to deal with ranges. You can see an element's range using the SET RANGE key-in.

Range Uses

A range is stored as two 64-bit integer triplets (XYZ low and XYZ high). This contrasts with MicroStation master units, with which a MicroStation user is familiar. Master units are stored as units-of-resolution (UORs) in double-precision floating-point numbers (C++ double). The reasons for using integers for element range include …

• Integers are fast to calculate compared to floating-point numbers
• Integers are fast to compare
• Integer comparison is exact, unlike comparison operations on floating-point numbers

The code example shows how to answer questions about ranges …

Does one range fall inside another?

Does one range overlap (intersect) another?

Scanning

MicroStation often scans a DGN model, looking for those elements that fit within a specified range. Because scanning compares two ranges using integers, the arithmetic is fast.

Views and Scanning

For example, MicroStation may want to find those elements that are contained in a particular view. When user issues a 'fit view' command, MicroStation needs to know those elements whose ranges will be used to calculate the new view dimensions.

Fence and Scanning

Another example is a fence. User want to perform some operation on those elements that are bounded by a fence. MicroStation scans the DGN model using the fence range to find elements that are contained by the fence.

Scanning is a Coarse Filter

Because an element range is a bounding block (or shape) the result of a scan is by nature inexact. A scan is a quick test that tells you what elements are interesting. However, 'interesting' is a loose term — it lets you find candidate elements fast. You may want subsequently to implement a more precise analysis of those candidates.

Custom Scanning

You may want to implement some custom scanning. For example, you might want to test whether one shape is inside another: a scan lets you establish quickly that topology.

Python API

MicroStation Python doesn't have a scanning API. Other MicroStation development languages (even MicroStationVBA!) do have a scanning API. So, if you want to find those elements in, say, a view or fence, then you'll have to roll your own.

scan_range class

I'm here to help. I've written a scan_range class that inherits from MicroStation Python ScanRange. I've added several constructors and comparison methods …

Constructors include …

• from_int() creates a scan_range class instance from six integers
• from_fence() creates a scan_range class instance from an existing fence
• from_element_id() creates a scan_range class instance given the ID of an existing element
• from_element() creates a scan_range class instance from an existing element
• from_element_handle() creates a scan_range class instance from an existing element
• from_drange3d() creates a scan_range class instance from a DRange3d

Methods include …

• is_outside() tests whether this scan_range falls entirely outside another ScanRange
• is_inside() tests whether this scan_range falls entirely inside another ScanRange
• is_congruent() tests whether this scan_range is congruent with another ScanRange
• spatial_relationship() determines whether this scan_range is inside, outside or overlaps another scan_range
• rectify_points() re-orders a set of points to determine the maximum and minimum of a range

Examples using scan_range

Some examples test the constructors, to confirm your suspicions about ranges. Others test the comparison methods, to shows the relationship between one range and another.

Fence

We often want to find the contents of a fence. One way to do that is to find those elements whose range falls within the fence range. I wrote a fence_helper class to add some useful methods.

For the purpose of this article, my primary reason for writing the helper is to get the range of a rectangular fence. fence_helper.get_fence_points() performs that task, whether the fence is defined by points or uses a DGN element.

Python FenceManager

If you work a lot with MicroStation fences, then familiarise yourself with Python's FenceManager.

I wrote this article and code to help you understand MicroStation element ranges. If you want to find, for example, the elements inside a fence then there are methods provided by FenceManager. Those methods are not restricted to a rectangular fence.

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

Start MicroStation and place some elements. You'll need to create some rectangles, some big, some small, to test this code. Put one small rectangle inside a larger rectangle to test the topology algorithm.

You'll need to place a fence to execute some code successfully.

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

---

Questions

Post questions about MicroStation Python programming to the MicroStation Programming Forum.