Site Tools


RhPicture Plug-in GDI Pen Object

Summary: A description of the GDI Pen object as exposed through the RhPicture plug-in


GDI+ Pen objects

GDI+ Pen objects are used to draw lines. They can simulate a wide range of behaviors, some of which are also available through the RhPicture plug-in.

Properties available in RhPicture Pen objects:

  • Color
  • Width
  • Cap style
  • Join style
  • Dash Pattern
  • Dash Cap style
  • Compound Pens

Properties not available in RhPicture Pen objects:

  • Custom Caps
  • Brush Fills
  • Alignment
  • Dash Pattern Offset
  • Custom Miter Limit
  • Local Transform Matrix
  • Dash Patterns in conjunction with Compound Pens

Most of these properties are self-evident and need little elaboration. However, the lack of predefined enumerations in VBScript requires us to specify these as integers, which is not self-documenting. Note that you do not need Pen objects to draw lines in the RhPicture plug-in. Every method that takes a Pen object is overloaded and can be called with a color and optional width parameter. In most cases this should be sufficient and makes a much simpler code:

Dim RhPicture : Set RhPicture = Rhin.GetPluginObject("RhPicture")
Call RhPicture.CreateImage(50, 50, vbWhite)
Call RhPicture.DrawLine(Array(10,30), Array(40,10), vbBlack, 5)

If you want to draw lines with dash patterns or special caps, you'll have to use an RhPicture Pen object. You can obtain a Pen object by calling one of the Pen creation methods on RhPicture:

Dim RhPicture : Set RhPicture = Rhin.GetPluginObject("RhPicture")
Call RhPicture.CreateImage(50, 50, vbWhite)
Dim PenObj : Set PenObj = RhPicture.CreateDashedPen(vbBlack, 5, , , , Array(1.0, 2.0))
Call RhPicture.DrawLine(Array(10,30), Array(40,10), PenObj)

You can store any number of Pen objects in your script and you can reuse them as often as you like. Pen objects are not bound to the RhPicture instance that created them and you can use them on any RhPicture object. There are two Pen creation methods available, the first one of which is overloaded:

RhPicture.CreatePen(Color As GDIColor) As GDIPen
RhPicture.CreatePen(Color As GDIColor, Width As Double) As GDIPen
RhPicture.CreatePen(Color As GDIColor, Width As Double, Cap As Integer) As GDIPen
RhPicture.CreatePen(Color As GDIColor, Width As Double, Cap As Integer, Join As Integer) As GDIPen
RhPicture.CreatePen(Color As GDIColor, Width As Double, Cap As Integer, Join As Integer, Compound() As Double) As GDIPen
RhPicture.CreateDashedPen(Color As GDIColor, Optional Width As Double = 1.0, _
                          Optional Cap As Integer, Optional DashCap As Integer, _
                          Optional Join As Integer, Optional Pattern() As Double) As GDIPen
Parameter Type Description
Color GDIColor A GDIColor instance.
Width Double The width of the pen in pixel units. (Pen width is subject to Transform distortion).
Cap Integer The start and end cap enumeration. See table below for valid numbers.
DashCap Integer The cap enumeration for dashes. See table below for valid numbers.
Join Integer The join enumeration. See table below for valid numbers.
Compound Double() An array of double values that define the compound sections of a pen. See below for further details.
Pattern Double() An array of double values that define the dash pattern for this pen. See below for further details.



Enumerations explained

Cap Enumeration flags for PEN constuctors
Flat Round Square Triangle Arrow Anchor Round Anchor Square Anchor Diamond Anchor
Cap = 0 Cap = 1 Cap = 2 Cap = 3 Cap = 4 Cap = 5 Cap = 6 Cap = 7


Dash Cap Enumeration flags for PEN constuctors
Flat Round Square
DashCap = 0 DashCap = 1 DashCap = 2


Line Join Enumeration flags for PEN constuctors
Bevel Round Miter
Join = 0 Join = 1 Join = 2


Dash patterns explained

In GDI+ (and almost everywhere else), dash patterns are defined as a series of gaps and dashes, whose length is relative to the width of the pen. The illustration below shows the Dash coordinate system of a Pen object. The width of this Pen object is 5 pixels and the perpendicular lines are the unit-divisors, each spaced 5 units apart along the spline of the Pen object:



If we define a simple dash pattern consisting of a single Dash-Gap combo using the code below, we'll get a pen object that draws dashes that are as long as the pen is wide:

Dim RhPicture : Set RhPicture = Rhino.CreateObject("RhPicture")
RhPicture.CreateDashedPen(vbBlack, 5.0, , , , Array(1.0, 1.0))



There is no limit to the number of Dash-Gap combos we can define, but we must always supply an array of positive numbers containing an even number of elements:

Dim RhPicture : Set RhPicture = Rhino.CreateObject("RhPicture")
RhPicture.CreateDashedPen(vbBlack, 5.0, , , , Array(1.0, 1.0, 2.0, 2.0))


A few different dash patterns.
(1.0, 1.0) (1.0, 2.0) (2.0, 1.0) (1.0, 0.2) (0.2, 0.2) (0.2, 0.2, 1.0, 0.2)


Compound pens explained

Compounds are best explained as perpendicular Dash patterns. Instead of drawing a succession of dashes along the line, a compound Pen object draws a number of parallel strands. Compounds are defined in much the same way as Dash patterns:

Dim RhPicture : Set RhPicture = Rhino.CreateObject("RhPicture")
RhPicture.CreatePen(vbBlack, 5.0, , , Array(0.0, 0.25, 0.75, 1.0))

Compound arrays are arrays of increasing doubles not smaller than zero and no larger than one. The code above yields the compound pen below:



A few different compound definitions.
(0.0, 1.0) (0.0, 0.25, 0.75, 1.0) (0.0, 0.45, 0.55, 1.0) (0.0, 0.2, 0.4, 0.6, 0.8, 1.0)
developer/rhpicture/gdipen.txt ยท Last modified: 2016/04/07 by sandy