10 - Scripting

1.0 Introduction

In this tutorial, we will walk you through the setup process and provide an overview of how to run your first Python script for Dips.

Topics Covered in this Tutorial:

• Python Environment
• RocScript
• Self-hosted Environment

Finished Product:

The finished product of this tutorial can be found in the Tutorial 10 Scripting.dips9 file, located in the Examples > Tutorials folder in your Dips installation folder.

2.0 Prerequisites

2.1 Dips Version 9

Before you begin, ensure you have the Dips program installed. You must have at minimum Version 9.001 in order to use this feature.

2.2 Python Environment

There are two methods to run a script, which differ in the Python environment used:

1. Running on RocScript Editor (for all levels of users):
• Download and install RocScript from RocScript Update History page.
2. Running on your own Python environment (for advanced users):
• Install the Dips Python API library.

Each method is detailed below.

3.0 Method 1: Using RocScript

3.1 Opening the RocScript Editor

In Dips:

1. Select Scripting > Launch RocScript Editor from the ribbon.
2. The RocScript Editor will launch in a separate application window.

3.2 Open a File

To open a file in the RocScript Editor:

1. Select File > Open File option from the menu.
   
   
2. Select the Tutorial.py Python file from the tutorial folder directory located in the Examples > Tutorials folder in your Dips installation folder.

3.3 Run the File

To run the file:

1. Click on the Run Python File button at the top right of the window:

The Tutorial.py script showcases a simple application of Dips Scripting. Utilizing functions from the Dips Python API library, it:

2. Launches the Dips application and a server at port 62535
3. Accesses the Dips model
4. Creates a Spot Mapping data set and adds it to the Orientation Data.
5. Creates a Stereonet 2D view and in that view:
   1. Adds a Text Tool.
   2. Sets and gets the first Traverse visibility and properties.
   3. Sets the Contours visibility.

3.4 Install Libraries (Optional)

In Dips:

1. Select Scripting > Manage Python Environment from the ribbon.
2. The RocScript WinPython Command Prompt will open.
   
3. Check the installed libraries with the command:

pip list

Pre-installed libraries include:

• The Dips Python API Library (i.e., DipsScripting 9.X.X on the list)
• Dependency Python libraries:
  • colorama
  • grpcio
  • iniconfig
  • packaging
  • pluggy
  • protobuf
  • Pygments
  • pytest
  • pytest-mock
  • typing_extensions
• Common Python libraries:
  • Pandas
  • Matplotlib

4. If you wish to install more libraries, use the command to do so:

pip install [library name]

4.0 Method 2: Using your Own Environment

The Python environment is made up of two parts which need to be installed:

1. The Python interpreter (Section 4.1 below)
2. The Code Editor (Section 4.2 below)

4.1 Install Python

1. Navigate to the Python downloads page (https://www.python.org/downloads/),
2. Select the Download for the desired release version.
Python 3.0.0 and later should be compatible; however, testing was performed using Python 3.11.2.
3. Scroll down and select 'Windows installer (64-bit)'.
4. Run the installer. Keep the defaults and select Install Now. Installation should complete successfully.

4.2 Install a Python Code Editor

Any code editor can be used, but we recommend you use Visual Studio Code.

To download and install Visual Studio Code:

1. Navigate to the Download page (https://code.visualstudio.com/download)
   
2. Select the Windows option
   
3. Run the installer and complete the installation.

4.3 Configure Editor for Python

Visual Studio Code (VSCode) has extensions which can be installed.

1. Navigate to the Extensions pane and search for Python.
   
   
2. Install the Python extension.
3. Restart VSCode.

4.4 Install the Dips Library

1. In VSCode, select View > Terminal in the menu to open a terminal.
   
   
2. Install the library using pip, which is a package manager that comes with Python:

pip install DipsScripting

If you are not using the latest release of Dips, you need to specify a library version that matches your Dips version. For example:

pip install "DipsScripting==9.1.0"

To find a list of available DipsScripting Python package versions, see Release History.

You can find your version of Dips by selecting Help > About in the Dips program.

The Dips Python API Library is now installed.

4.5 Open a File

In VSCode:

1. Select File > Open File in the menu:
   
   
2. Select the Tutorial.py Python file from the tutorial folder directory located in the Examples > Tutorials folder in your Dips installation folder.

4.6 Run the file

To run the file:

1. Click on the Run Python File button at the top right of the window.

You’ve successfully set up your Python environment to use Dips Scripting. You can build your own Python scripts for Dips now!

5.0 Resources

For more information on Dips Scripting, check out the following resources:

• Dips Python Reference Guide
• Dips Scripting help topic

This concludes the tutorial.