Getting Started with Geomatica and Python

Welcome and Let’s Get Started!

Are you new to development with CATALYST Professional and/or Python? If so, this is the right place to start!

This getting started guide will walk you through everything you need to know to begin building powerful solutions with CATALYST’s Python API.

Downloading and Installing CATALYST Professional

1. Download CATALYST Professional – https://catalyst.earth/products/catalyst-pro/
2. Run the installation, making sure to choose the correct licensing method based on your configuration. See our Licensing and Installation tutorials for more detailed steps: Tutorials – CATALYST.Earth
3. Python 3.6 is installed along with Professional

Professional’s Development Environments

There are three main environments to program with Professional and Python, each of which with their own value and purpose:

• Command Line: You can use command line to quickly test your installation and configuration. You can then also run scripts that you create through the command line window.
  1. In your start menu, type cmd and hit the enter key
  2. The Command Prompt will open
  3. In the Command Prompt, type “C:\Program Files\Python36\python.exe” and hit the enter key
  4. Type import pci
  5. If no error message appears then the PCI library has been correctly imported
  6. To check the version of Professional that is running type pci.version
• Focus: Focus is a desktop Geo-image and vector viewing, editing, image processing and analytical environment. It comes with a Python window that allows users to execute short Python scripts directly in Focus.
  1. Open Focus from the Professional toolbar
  2. In the dropdown menu bar, click on Tools > Python Scripting…
  3. In the Python Scripting window, type in import pci
  4. Click on the run button 
  5. If no error message appears then the PCI library has been correctly imported
• IDE (Integrated Development Environment): IDEs are tools that help developers program. An IDE can help you manage and maintain large coding projects, multiple coding projects and even help you learn. There are a number of different IDEs available for free download and here are some of our favorites:
  • IDLE – This is the default IDE that comes with your installation of python
  • Notepad++ – This is a simple lightweight IDE and is great for beginners. However, you should graduate to a more powerful IDE as your skills develop
  • PyCharm – Developed by Jet Brains, it is a powerful IDE with a free community edition and appropriately priced professional edition. This is one of our favorite IDEs to use for more advanced scripting and programming.

If you receive an error message while importing the PCI library, the Professional Installation FAQ outlines potential solutions.

Basics of Python

Now that you have installed Python on your computer you can begin to create scripts to automate various workflows. However, you will need to make sure that you have a basic understanding of Python concepts. We have provided a few links to useful tutorials which will help you learn about Python basics:

• Official Python getting started page – Includes links to various tutorials and Python specific resources
• Beginner’s Guide to Python – The official python guide for beginners. It is a great resource for taking your first few steps with python in general
• Learn Python the Hard Way – Free Online book. This is our personal favorite resource for beginners to learn python

Relevant Documentation & Resources

There are a number of help documents which will be very useful resources for looking up specific Professional algorithms or Python concepts.

Documentation

• CATALYST Online Help – Provides information about each Professional algorithm that you can run in Python. For each algorithm, there is an explanation of the use and technical details of the algorithm and a list of each of the algorithm’s parameters. Before you run a Professional algorithm in Python, check the help to make sure that you have listed all of the required parameters.
• CATALYST Python API Documentation – CATALYST Python API help documentation
• Python 3.6 Official Documentation – Information about all Python concepts is available in this documentation.

Resources

• YouTube Video Guides – A YouTube playlist with official PCI Geomatics videos to demonstrate useful programming concepts with CATALYST’s Python API
• Professional Tutorials – Step-by-step tutorials which outline various workflows in the software. There is a Python section which includes additional CATALYST’s Python API tutorials.
• Geomatica Cookbook – Dozens of useful and simple recipes for doing common GeoImage processing with CATALYST ’s Python API. Great for people new to CATALYST and/or Python
• NumPy – CATALYST ’s Python API allows users to build custom functions. NumPy is used as a base for storing and manipulating pixel information (more advanced)

Writing your first Python script with Professional

You should now have an understanding of basic Python concepts and be ready to use that knowledge to run your first Professional algorithm in Python. As previously mentioned, there are additional Professional Python tutorials. We would recommend starting with the beginner tutorials:

• Running a Professional Algorithm – Learn how to run a single Professional algorithm using Python
• Chain Professional Algorithms Together – Learn how to chain multiple Professional algorithms together in Python
• Creating a Basic Batch Professional Process – Learn how to process a batch of images or files with Professional algorithms in python

Best Practice Tips

Check for a Professional Algorithm before building your own function.

• Background – The CATALYST Python API can be broken down into two main areas, the Professional Algorithms and the CATALYST Python API. The Professional Algorithms are a set of over 550 GIS, remote sensing and image processing algorithms that have been built, maintained and enhanced by PCI over many years. These algorithms are fast, simple to run and powerful. The CATALYST Python API, on the other hand, gives developers access to modules and classes that can be used to build custom algorithms, which can process data in any way the developer wishes.
• Tip – When you want to perform a specific type of process on your data, first check to see if one or a combination of the Professional Algorithms will do the job before creating your own custom algorithm using the CATALYST Python API modules and classes.
  • Do a keyword search in the Professional Online Help to see if an algorithm or algorithms exist that perform the process you want.
  • If you cannot find a Professional Algorithm that performs the desired process, use the CATALYST Python API to build the algorithm yourself.
  • Alternatively, you can Google to see if a 3rd party open source library has a function that can perform the desired process

Use Keyword Arguments when running Professional Algorithms

• Background – Professional Algorithms are designed to be simple to setup and run, but also expose many advanced processing parameters for users that wish to tweak every option. As a result, Professional Algorithms may have many parameters that are defaulted. This creates a situation where an algorithm may have many arguments, but only a small number of them need to be explicitly specified.
• Tip – Always use keyword arguments when calling (running) a Professional Algorithm in Python. The keywords are the names of the parameters in the Professional Online Help
  • Go to the Online Help and find the algorithm of interest
  • Locate the Parameters table
    
    
    
  • Call the algorithm by only passing the arguments you need or wish to manually set by using the parameter name followed by the equal sign (=), which is then followed by the setting for that parameter. The parameters that have not been specified below have been left as their default values.
  • You do not need to pass any other arguments (parameters)

You are now ready to start developing Python scripts using CATALYST Professional!