HowTo: Create an Embedded Script

Version: 16.2

Table of Contents

Preface
- Related Links
- Assumptions
Getting Started
- Creating the Script
- Running the Script
Details

Preface

This document discusses the basic creation of a MineSight® Grail embedded script. It will go through the process of creating a script that displays "helloworld!" in the MineSight® 3D message window.

Note that an embedded script has some extra components that must be considered above and beyond the basic MineSight® Grail Script.

Assumptions

It is assumed that you are familiar with the MineSight® 3D, and the basic mechanics of a python script.

To execute a MineSight® Grail embedded script you must run the script inside the MineSight® 3D. Any script that references the grail.ms3d module, has this requirement.

Getting Started

The process for creating and running an embedded script involves first, editing your script, then executing your script within MineSight® 3D.

Creating the Script

To start the creation of a basic helloworld script open the $(medexe)\scriptssamples directory and copy the em-boilerplate.py to a new file called helloworld.py.

Now open the helloworld.py script and go to the run_code function, which will look something like this,

def run_code():

    """Sample 'function' in embedded script.

    This function will write some text out the message

    window, but you can have it do anything you like.

    """

    print "Boilerplate."

Replace the "Boilerplate" text with "Helloworld!".

"""Example of Helloworld embedded script.

This script illustrates how to print helloworld to the MineSight 3D

message window.

LICENSE AGREEMENT

The Original Code is "helloworld.py".

The Initial Developer of the Original Code is Leica Geosystems.

Portions created by Leica Geosystems are Copyright (C) 2014 year.

Leica Geosystems. All Rights Reserved.

"""

from grail import gsys

def run_code():

    """Displays helloworld to the message window."""

    print "Helloworld!"

gmain = gsys.GMAIN(run_code)

gmain.run()

Download the complete helloworld.py script.

Running the Script

To execute the helloworld.py script, you must,

Start up MineSight® 3D.

Select File->Run Script...

Use the file chooser to select helloworld.py

After selecting the file, the script will execute. The "Helloworld!" string will be displayed within your MineSight® 3D message window.

Details

This simple example can be useful for discussing a few points regarding embedded scripts,

Using grail.ms3d

Any script that has a "from grail.ms3d import..." line within it is termed a MineSight® Grail embedded script. This means that the script can only be executed within the context of a MineSight® 3D environment.

Notice, that since MineSight® IP is also within MineSight® 3D you can use embedded features within a MineSight® IP script.

What is gmain?

The gmain function is a standard entry point for all scripts. This is the location in the script that any MineSight® product can communicate through.

Of the numerous messages that can travel through a gmain function you are generally only concerned with the messages.gRUN message. All messages can be found in the grail.messages module.

Starting with v4.70 we introduced the "GMAIN" function to help simplify creating a script entry point. Now all you have to do is,

from grail import gsys

def main():
# your code

gmain = gsys.GMAIN(main)

Print Statements

All print statements will appear in the MineSight 3D message window.