PCI Geomatics -

# Overview

This tutorial outlines how to access channel statistics and segment IDs in python. When writing more detailed scripts, you often require these values as inputs to algorithms.

# Prerequisites

• Geomatica 2016 or a more recent installation
• Python 101 (basic understanding of python coding concepts)
• try, except, finally statements
• How to access modules and classes
• How to call a function
• Some experience programming with Geomatica (recommended)

# Tutorial

The first section of this tutorial outlines how to extract channel statistics using the HIS algorithm. The second section of the tutorial demonstrates how to extract segment numbers for various segment types (Bitmaps, vectors, PCTs, etc.)

## 1. Import modules & setup input

The first step is to import the Geomatica modules we will be calling in this tutorial and setting up the variables that will point to our input and output directories and files.

 ```1 2 3 4 5 6 7``` ```# ***PART 1: Import modules & setup input*** print "PART 1: Import modules & setup input" from pci.exceptions import * from pci.his import his from pci.nspio import Report, enableDefaultReport from pci.api import datasource as ds image = r"I:\Data\Tutorial\Python\HIS\irvine.pix" # Change this to your input image ```

Lines 3 to 6 import the required algorithms, as outlined above. On line 7, image is a variable that contains the path to your pix file. You can use any file to run through this tutorial. However, in order to extract all of the segment IDs, your file will need to include those type of segments. You can always manually add extra segments to your file for testing purposes.

## 2. Extract Channel Statistics with HIS

In order to access channel statistics you will need to run the HIS algorithm. Usually, HIS outputs a histogram to the terminal however this is not always required by the user. The NSPIO module is used to control the reporting of algorithms.

 ```8 9 10 11 12 13 14 15 16 17 18 19 20 21``` ```# ***PART 2: Extract channel statistics with HIS*** print "PART 2: Extract channel statistics with HIS" try: Report.clear() stats = [] his(file=image, dbic=[1], imstat=stats) except PCIException, e: print e except Exception, e: print e finally: enableDefaultReport('term') ```

In this tutorial reporting is turned off, although reporting can also be switched to terminal or file as outlined in this tutorial. On line 10 a try statement is started and on line 11 reporting is cleared. Before you call HIS, you will first need to create an empty list (stats). HIS has a parameter IMSTAT which includes all of the statistics and when you run HIS, the statistics will be saved back to the empty list. On line 13 HIS is called using keyword arguments. These types of arguments are further explained in this tutorial. The dbic parameter specifies the channel from the input image that you wish to extract statistics from. When using HIS to extract channel statistics you can only specify a single channel. The imstat parameter is now set to the empty list (stats) that you defined on line 12. On line 16, the two except clauses begin, which will print out error messages if the try statement fails. On line 20 a finally statement is executed which switches the reporting back to terminal.

Now that you have the statistics saved to a list you can access the required statistics from the list.

 ```22 23 24 25 26 27 28``` ```# After running HIS, the statistics are saved into the imstat parameter. You can then extract specific stats from the imstat list chan_num = stats[0] chan_mean = stats[1] min_pixel_val = stats[10] max_pix_val = stats[11] print_stats = "Channel {0} Statistics:\nMean Pixel Value: {1}\nMinimum Pixel Value: {2}\nMaximum Pixel Value: {3}\n" print print_stats.format(chan_num, chan_mean, min_pixel_val, max_pix_val) ```

The Geomatica Help for HIS lists all of the channel statistics that are saved to the IMSTAT parameter. Keep in mind that the first imstat value (channel number) would be imstat[0] as per python’s numbering scheme. A few example statistics are listed in the code above. Note that the minimum and maximum pixel value variables correspond to imstats’ lowest and highest grey level statistics. You can then use these statistics later on in your script as required.

## 3. Extract Channel Count & Information

Additional information that is useful to extract from pix files is the channel IDs. These values are often required as inputs for algorithms. You can also check the list of IDs after running an algorithm, to determine which channel was most recently added.

 ```29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44``` ```# ***Part 3: Extract channel count and info*** print "Part 3: Extract channel count and info" with ds.open_dataset(image, ds.eAM_READ) as pix: # Get channel count chans = pix.chan_count print "Channel Count: ", chans # Get channel 1 info chan1_info = pix.get_channel_info(1) chan1_data_type = chan1_info.data_type print "Channel 1 Data Type: ", chan1_data_type # Get channel 1 history chan1_hist = pix.get_history_io(1) chan1_hist_list = chan1_hist.read_history_events() print "Channel 1 History:" for event in chan1_hist_list: print event.id, event.message, event.timestamp ```

Before you can access the channel IDs you will need to first open the dataset using the datasource open_dataset function. You want to open the datasets in a with clause to ensure that they will be automatically closed when the clause is exited. You will need to specify two inputs; the image and the access mode. In this case we opened the dataset with read/write capabilities.

Once the dataset is open you can access the channel information. The Geomatica Python API help lists a number of functions that can be used to access channel information. In this specific case we are interested in accessing the channel count (chan_count), channel information (get_channel_info) and channel data type (data_type), and channel history (get_history, read_history_events). On line 33 and 34 the number of channels in the raster dataset is determined and then printed. On line 36 the channel information is accessed. From the channel information you can extract the data type as shown on line 38. You can also extract the channel history of a specified channel as per line 40. From the channel history object you can create a list of each history event (line 41) and then extract each event’s ID, message and timestamp (line 43-44).

## 4. Extract Segment IDs

You can also extract segment IDs using the Geomatica Python API. Similar to the channel count, this information is helpful in determining segments in a pix file and segments added by an algorithm.

 ```45 46 47 48 49 50 51 52 53 5455``` ```# *** Part 4: Extract segment IDs and info*** print "\nPart 4: Extract segment IDs and info" # Get vector segment IDs vec_ids = pix.get_vector_io_ids() print "Vector IDs: ", vec_ids # Get bitmap IDs and info bit_ids = pix.bitmap_ids print "Bitmap IDs: ", bit_ids # Get PCT IDs and info pct_ids = pix.get_pct_io_ids() print "PCT IDs: ", pct_ids ```

Similar to the previous step, you will use Geomatica Python API functions to extract segment IDs from the opened pix file. In this example the IDs of the Vector, Bitmap (masks) and PCT segments are extracted, however the API documentation lists all possible segment types (sections 3.3.4.4 – 3.3.4.13). On line 48 the get_vector_io_ids() function is used to create a list of all of the vector segment IDs. Similar functions are used on lines 51 and 54 to list the bitmap (bitmap_ids) and PCT (get_pct_io_ids()) IDs, respectively. Once you are familiar with the method of calling these functions you can also take a look at other functions that relate to each type of segment in the API help.