First practical session: introduction

Goal

The goal of this session is to make you comfortable with Python and the combination of Python with C++.

The practical assignments must be made in a combination of Python and C++. We assume that you have general programming skills, basic knowledge of C++ and no knowledge of Python. You will be provided with bits of Python/C++ example code to give you a quickstart. In this practical session, you can follow the next instructions to learn how to program in Python and how to use the example code. Following these instructions is facultative but recommended.

First hour: learn Python

Python is easy to learn, easy to use, makes programming take less time and more fun. To start learning, (quickly) read and/or try the Python Short Course (via: Beginners guide or Programmers, which also points to the more extensive Python Tutorial).

Second hour: learn to combine Python and C++

Python is great but it has a weakness: 'for-loops' are slow. Therefore, for operations on pixels, we will use C++. These instructions illustrate how to combine Python and C++.

In the following instructions, several directory names are suggested, but you may use alternative directories if you insist.

Step 1: Get the introduction files

• If you are a non-AI student, ask Jean-Paul for a temporary account.
• Make a directory for the practicals:
  mkdir ~/hwr
• Copy the introduction files:
  cp -r /home/student/hwr/toolbox ~/hwr/
cp -r /home/student/hwr/introduction ~/hwr/
  Note: the files are described in the Appendix below.

Step 2: Get a sample image

• Download a source image here. Be careful to select a .tif file named like NL_HaNa_H2_7823_xxxx.tif, not a file with 'colorized' in the name or a file with extension .kdkxml. The password is on Nestor under the "Course Documents" button. Store the image in the temporary storage directory /dev/shm (it is flushed at a reboot). These files are big; keep an eye on disk space usage. Type df -h to see how much space is available.
• The sample code only works with raw .pbm/.ppm/.pgm files (simple bitmaps; .pbm=black/white, .ppm=color, .pgm=grayscale). Convert the downloaded image to raw PPM:
  convert -compress LZW /dev/shm/NL_HaNa_H2_7823_xxxx.tif /dev/shm/NL_HaNa_H2_7823_xxxx.ppm
  Note: the 'compress LZW' option is misleading; there is no compression in the PPM format, but this ensures that the file is stored as raw .ppm (instead of ascii .ppm). You can remove the .tif version of the image.

Step 3: Try the introduction files

• Compile the C++ code:
  cd ~/hwr/introduction
make
• Try the cropper example:
  python example-crop.py /dev/shm/NL_HaNa_H2_7823_xxxx.ppm /dev/shm/cropped.ppm
  It will create an image (cropped.ppm) of a part of the original image.
• Try the feature extractor example:
  python example-featextract.py /dev/shm/cropped.ppm
  It will compute and show a simple feature vector, a list consisting of just one number.

Step 4: Understand the introduction files

• Verify that 'make' creates six new files using:
  make clean
make
ls -ltr
  The newest files are shown at the bottom of the list. The generated files with extensions .py and ._so are created from C++ code and make sure that the code can be called from Python code.
• Look in the source code of example-crop.py and see how it can call a function in croplib.h and croplib.cpp using croplib.i. Also inspect pamImage.h and see how it's done in the Makefile. (You do not have to look in pamImage.cpp.)
  Note: PamImage is a handy object that does the reading and writing of image files for you.
• Look in the source code of example-featextract.py, featlib.h, featlib.cpp and featlib.i to see how it works.

If you are finished early, you are suggested to start working on Assignment 1.

Appendix: Description of the files

Files in introduction/

File	Description
croplib.cpp	Crop p*m images.
croplib.h	Header for croplib.cpp.
croplib.i	Interface between C++ and Python for croplib.
example-crop.py	Shows how to use croplib. Crops an image.
example-featextract.py	Shows how to use featlib. Computes a simple feature vector containing one value: the fraction of dark pixels.
featlib.cpp	Example feature extraction code: computes the fraction of dark pixels.
featlib.h	Header for featlib.cpp
featlib.i	Interface between C++ and Python for featlib.
Makefile	Instructions for 'make' to compile the code.

Files in toolbox/

The .i files define an interface between C++ and Python. Swig uses them to create a Python wrapper around the C++ code.