Welcome and Let’s Get Started!
Are you new to development with Geomatica 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 Geomatica’s Python API.
Topics include both written and video instructions:
- The very simple installation process
- Tour of development environments
- Python basics
- Useful developer resources
- Developing your first Geomatica Python scripts
- Best practices
Downloading and Installing Geomatica for Development
Installing Geomatica for Python development is as easy as 1, 2, 3!
- Download the Geomatica installer for Windows
- Double click on the installer (Geomatica.exe) and follow the install wizard
- Contact your local sales representative to help you find the right package
Note: Geomatica comes with a free trial license, so you can begin developing right away!
Tour Geomatica’s Development Environments
There are three main environments to program with Geomatica and python, each of which with their own value and purpose:
- Command-line: the Windows Command Prompt or Linux terminal can be used to quickly check your installation and configuration and quickly test small blocks of code or Geomatica Algorithms before applying them to your larger script/program.
- In your start menu, type cmd and hit the enter key
- The Command Prompt will open
- In the Command Prompt, type c:\python27\python.exe (or to where you installed Python), and hit the enter key
- Type import pci
- If no error message appears then the PCI library has been correctly imported
- Geomatica’s 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 Python scripts directly in Focus
- Open Geomatica’s Focus
- In the dropdown menu bar, click on Tools > Python Scripting…
- In the Python Scripting window, type in import pci
- Click on the run button
- 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 Geomatica 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:
- Python Introduction Tutorial (By PCI Geomatics) – By beginner for beginners. A simple python introductory tutorial.
- 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 Geomatica algorithms or Python concepts.
- Geomatica Online Help – Provides information about each Geomatica 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 Geomatica algorithm in Python, check the help to make sure that you have listed all of the required parameters.
- Geomatica Platform API Documentation - Geomatica Python API help documentation
- Python 2.7 Official Documentation – Information about all Python concepts is available in this documentation.
- Geomatica Developer Zone – Access to developer resources such as tutorials, video guides, cookbooks, documentation and more
- YouTube Video Guides – A YouTube playlist with official PCI Geomatics videos to demonstrate useful programming concepts with Geomatica’s Python API
- Geomatica Tutorials – A set of beginner, intermediate and advanced tutorials to help you as you develop more intricate and complex solutions
- Geomatica Cookbook – Dozens of useful and simple recipes for doing common GeoImage processing with Geomatica’s API. Great for people new to Geomatica and/or Python
- NumPy – Geomatica’s Platform API allows users to build custom functions. NumPy is used as a base for storing and manipulating pixel information (more advanced)
Writing your first Geomatica Script
You should now have an understanding of basic Python concepts and be ready to use that knowledge to run your first Geomatica algorithm in Python. As previously mentioned, there are three categories of Geomatica Developer tutorials. You can now begin with the first beginner tutorial.
- Running a Geomatica Algorithm – Learn how to run a single Geomatica algorithm using Python
- Chain Geomatica Algorithms Together – Learn how to chain multiple Geomatica algorithms together in Python
- Creating a Basic Batch Geomatica Process – Learn how to process a batch of images or files with Geomatica algorithms in python
Best Practice Tips
1. Check for a Geomatica Algorithm before building your own function
- Background – The Geomatica Python API can be broken down into two main areas, the Geomatica Algorithms and the Geomatica Platform. The Geomatica 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 Geomatica Platform, 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 Geomatica Algorithms will do the job before creating your own custom algorithm using the Geomatica Platform modules and classes.
i. Do a keyword search in the Geomatica Online Help to see if an algorithm or algorithms exist that perform the process you want.
ii. If you cannot find a Geomatica Algorithm that performs the desired process, use the Geomatica Platform Python API to build the algorithm yourself.
iii. Alternatively, you can Google to see if a 3rd party open source library has a function that can perform the desired process
2. Use Keyword Arguments when running Geomatica Algorithms
- Background – Geomatica 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, Geomatica Algorithms may have many parameters that are defaulted. This creates a situation where a Geomatica 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 Geomatica Algorithm in Python! The keywords are the names of the parameters in the Geomatica Online Help
i. Go to the Geomatica Online Help and find the algorithm of interest
ii. Locate the Parameters table
iii. 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.
iv. You do not need to pass any other arguments (parameters)