Interactive Numeric Python Shell

  • Introduction
  • Environment
  • Functions
  • Commands
  • Examples
  • Python Shell Help


    The OpenEV Python Shell provides access to image data in a Python scripting environment with built-in mathematical functions (supplied by the Numeric Python module). The OpenEV Python Shell adds a thin extra layer of interpretation to ordinary python, allowing a slightly different syntax to be used for some frequently used functions for typing convenience (no brackets). The core convenience functions (called commands) are registered automatically when the Python Shell launches, and have more argument checking infrastructure than regular python functions. To illustrate the difference between python and command syntax, the following example shows two ways of saving an array from the Python Shell environment to a file:

    save my_array my_filename
    Extension modules with other commands may be registered using the core command loadext, but commands require more overhead to implement and in most cases it is preferable to use the ordinary python syntax.

    If you're not familiar with Python or Numeric Python (NumPy) here are some references:


    At startup (from the Edit/Python Shell menu item) the Python environment automatically imports functions from Numeric and gdalnumeric, and registers the core commands. Numeric provides Numeric Python and gdalnumeric provides functions to access OpenEV image data.

    The shell consists of a command input window (bottom) and an output window (top). Aside from the registered commands, it behaves in the same way as the Python command line interpreter. Use the up and down arrow keys to scroll through previous command history.

    OpenEV Functions:

    In addition to the functions imported from Numeric python, OpenEV's Python shell includes the following functions:

    Core commands:

    Commands make use of an infrastructure that simplifies usage and help access for commonly used procedures that interact with the main OpenEV application or describe the local environment. These commands are intercepted and parsed before being passed to the shell's python interpreter, and are entered with the command and arguments separated by spaces rather than by round brackets and commas. Commands cannot be loaded or used in a regular python shell; they only have meaning within the context of OpenEV.

    Core command list:

    1. newview- create a new OpenEV view.
    2. view3d- display a dem and drape in 3D mode in the current OpenEV view.
    3. get- grab data from the currently active OpenEV view/layer..
    4. show- display a Python Shell array or GvShapes variable in an OpenEV view.
    5. clearview- clear the current OpenEV view.
    6. save- save a Python Shell array or GvShapes variable to a file.
    7. loadext- register commands from an extension module (command equivalent of python's import keyword).
    8. macro- run a sequence of commands/Python statements from a text file.
    9. journal- save text entered at the Python Shell command line to a text file.
    10. locals- list this session's local variables and their type codes.
    11. help- display help for a function or command.
    12. functions- list loaded python functions, or scan a module for functions.
    13. commands- list registered commands.


    Here is a small tutorial that illustrates simple python usage and some of OpenEV's python functions; for a more comprehensive general tutorial, see the tutorial.

    Example 1:

    Load a file into a Numeric python array:
        array1 = LoadFile(``)
    Display it in the current view:
    To get the Region Of Interest (ROI) marked on the image:

    1. launch the Edit toolbar using the menu entry Edit/Edit toolbar.

    2. select "Draw ROI" to activate the ROI tool.

    3. use the ROI tool to mark a region (left click to start drawing, drag, release to finish)

    4. roi() returns the ROI in (x, y, width, height)

    Use the ROI tool to get a subarray:

    1. mark out an ROI with the tool on the image

    2. array2 = get_roi(array1)

    To save array2 to a new file:

    Numeric python functions such as ones and array can also be used to create and manipulate arrays:

    To create a floating point array of ones with 5 rows and 6 columns:

    Reset rows 1 to 4, columns 1 to 5 of the array with some values:

    Square it:

    Display it in the current view:

    Some important points to note are:

    1. Numeric python arrays are indexed from zero.

    2. In slicing a Numeric python array using index range N:M, elements N, N+1, ...M-1 are included.

    Example 2

    We are starting with Python shell (Edit->Python Shell... menu item). You should load some raster file into OpenEV to work with.

    Python Shell Help

    The python shell has three commands used to provide help on functions and commands:
    1. help- display help for a function or command.
    2. commands- list registered commands.
    3. functions- list loaded python functions, or scan a module for functions.
    These commands make use of python __doc__ strings and any help text files that are registered. Help text files should only be used when there is some reason for not updating the python __doc__ string itself (eg. if documentation were going to be available in multiple languages, or if the package is from a third party and you don't want to use the doc string), or if the python documentation is fine but it is desirable to display help for some functions/commands that are not loaded so that the user is made aware of them. In the latter case, the help text file should be regenerated from the python documentation each time one of the functions' documentation changes (at least for releases). Help text files may have entries of the following three formats:
    Module: my_module
    Group: my_group
    Html: my_html.html
    Module: my_module
    Html: my_html.html
    Module: my_module
    Html: my_html.html
    where my_command, my_func, and my_builtin are a user-defined command, function, and builtin (bound C) function respectively. The Html entry is used to indicate an html file with more information, and is optional (currently, the python shell will not do anything with html information other than store the name of the link- this may be used in future though). The Module name is required to deal with the case of two modules defining different commands/functions with the same name. The COMMAND_NAME, FUNCTION_NAME, BUILTIN_NAME, Module, and Html parts of the text file are case-sensitive (ie. an error will occur if the case is not as above). See's RegisterHelp function for how to register a help file with the interpreter (this function determines the location of gvcorecmds_help.txt assuming that it is in the same directory as, and loads the text from it if it is present). The suggested convention for text help files is that if they are needed, they be placed in the same directory as the commands/functions they relate to, and have the same name as the command module, minus the '.py', plus '_help.txt'.