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 crash course. Start at "Interactive" and stop after one hour.

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 Axel 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/`

File	Description
pamImage.cpp	Read and write .pbm/.pgm/.ppm files (black/white, grayscale, color respectively) (you don't need to look inside this file).
pamImage.h	Header for pamImage.cpp; look here to see what you can do with a PamImage object.
pamImage.i	Interface between C++ and Python for pamImage.
word.py	Object for word zones and transcription (needed for later assignments).
wordio.py	Reads and writes .words files (needed for later assignments).
wordsline.py	Object for text line zones and associated word zones (needed for later assignments).

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

Last modified: 8 May 2009, by Axel Brink.

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.