Site Tools

GDI Bitmap Extension for RhinoScript

Developer: RhinoScript
Summary: A plug-in which exposes the Microsoft GDI+ API to RhinoScript.

The Graphics Device Interface (or GDI) in Microsoft Windows is a base library for all platform graphics calls. Rhino supports a newer version of these libraries called GDI+ which enables the developer to use advanced drawing techniques such as anti-aliasing, transparencies, gradients, and cleartype fonts. The essentials of GDI+ are now available for RhinoScripters through the use of this plug-in. This project is aimed at those scripters who need to either analyze or create graphic data through automated processes. It is not a graphic editor and it is not for you if you're unfamiliar with RhinoScript.

For further questions and requests, please: Contact the author.


Download the plug-in, the Monkey autocompletion file, and the example scripts. Install instructions are located inside the Archive.

Nested Object definitions

RhPicture contains several Object definitions which are available only through RhPicture. These objects all have their own wiki pages with information:

Namespace description

Since this project comes with autocompletion definitions for the Monkey Script editor, I will not discuss every function in this plug-in. Rather, I will give you a small breakdown on how the thing fits together from a logical point of view. For a more in depth reference to function parameters, see the other pages of this wiki group.

Before you can use the tools exposed in this plug-in, you need to create an instance of it in your script. There's no limit to the amount of instances you can make, but be aware that every one potentially stores a large bitmap in your computer memory. To create a new instance of the RhPicture plug-in, do the following:

 Dim RhPicture
 Set RhPicture = Rhino.GetPluginObject("RhPicture")

Note that autocompletion in Monkey only works if you name this variable “RhPicture”. Once the subroutine completes the instance will be destroyed and the memory will be released. It is usually considered good practice to specifically release object instances once you no longer need them, thus:

 Dim RhPicture : Set RhPicture = Rhino.GetPluginObject("RhPicture")
 'Do whatever it is you do in here...
 Set RhPicture = Nothing

File IO methods

Once you have your RhPicture instance, you can call its methods. By default, any new instance does not contain an image yet. You'll either have to load or create one before you can start drawing. There are several ways in which to load an image into an RhPicture instance:

  RhPicture.LoadImage() As Boolean
  RhPicture.LoadImage(ImageFileName As String) As Boolean
  RhPicture.CreateImage(Width As Integer, Height As Integer) As Boolean
  RhPicture.CreateImage(Width As Integer, Height As Integer, Background As GDIColor) As Boolean
  RhPicture.LoadImageFromViewport(Optional ByVal ViewportName As String, _
                                  Optional ByVal Width As Integer, _
                                  Optional ByVal Height As Integer, _
                                  Optional ByVal IncludeTitle As Boolean = True) As Boolean

The RhPicture plug-in can load and save images in the following file formats:

File format Extensions Description
Bitmap *.bmp The typical windows image format. Does not work well with Alpha channels and has no compression.
Memory Bitmap *.rle A geeky format you're unlikely to encounter.
JPEG .jpg;.jpeg Image format designed for photography. Does not contain Alpha channel information but has good lossy compression.
Gif *.gif Image format designed for web viewing. Supports only paletted colors and single bit Alpha channels. RhPicture does not support animated gifs.
PNG *.png Image format designed to get around the limitations of GIF images. Supports full Alpha channels and lossless compression. The format of choice for todays discriminating programmer.
EXIF *.exif A JPEG flavor used in digital cameras that stores camera information such as shutter speed and exposure.
TIFF .tif'.tiff An extremely versatile format with lots of options. RhPlugin does not support multi-layered tiffs.
Icons *.ico Windows icon format. Poorly supported in RhPicture.

All image data inside RhPicture instances is stored as 32bppARGB (32 bits-per-pixel Alpha Red Green Blue) meaning that JPEG, GIF, and some TIFF and PNG compression options are lost when they are loaded. At all times you can display or save the image contained in an RhPicture instance using:

  RhPicture.SaveImage() As Boolean
  RhPicture.SaveImage(ImageFileName As String) As Boolean
  RhPicture.ShowImage() As Boolean
  RhPicture.ShowImage(ViewerTitle As String, Optional Stretch As Boolean = False) As Boolean
Image viewer screenshot.
LMB is used for panning (panning beyond the viewer area is not allowed)
MMB-Scroll is used for zooming (zooming is restricted to 10%~5000% domain).

Analysis methods

Once you have your image (be it loaded or created), you can query its properties. There are both global and local properties:

Global Properties
Name Description
IsImage() Returns TRUE if an image is currently loaded, FALSE if there is no image available.
Width() The width of the loaded image in pixels or NULL on error.
Height() The height of the loaded image in pixels or NULL on error.
IsOnBitmap(x, y) Returns TRUE if the specified coordinate (in pixels) is on the bitmap surface.
AddPointCloud(pt, w, h) Adds a pointcloud with a single point for every pixel in the image. The points are assigned the same colour as the source pixel, minus the alpha information.

Local Properties
Name Description
GetPixel(x, y) Returns the color of the pixel at (x,y) or NULL if the coordinates are off the image.
SetPixel(x, y, color) Sets the color of the pixel at (x,y).
Red(x, y) Returns the amount of red (0~255) of the pixel at (x,y) or NULL on error.
Green(x, y) Returns the amount of green (0~255) of the pixel at (x,y) or NULL on error.
Blue(x, y) Returns the amount of blue (0~255) of the pixel at (x,y) or NULL on error.
Alpha(x, y) Returns the amount of alpha transparancy (0~255) of the pixel at (x,y) or NULL on error.
Hue(x, y) Returns the hue value (0.0~360.0) of the pixel at (x,y) or NULL on error.
Saturation(x, y) Returns the colour saturation (0.0~1.0) of the pixel at (x,y) or NULL on error.
Luminance(x, y) Returns the colour luminance (0.0~1.0) of the pixel at (x,y) or NULL on error.

Drawing methods

There are many methods available for drawing geometry. See this wiki page for more details: RhPicture drawing routines.

Filter methods

There are many methods available for applying effects and filters to RhPicture images. See this wiki page for more details: RhPicture filter routines.

developer/rhinoscriptimageextension.txt · Last modified: 2020/08/14 (external edit)