Jack Whitham

Software Engineer

Thumbnail

Thumbnail is a Python extension (Python + C) that was written to support the PhD work of my brother Roger. It carries out two tasks:

  • Generate thumbnail images for documents and media files.
  • Interface to Flash applets via Local Connection, allowing text messages of up to 256 bytes to be sent to and from Flash.

Using the Thumbnail extension, a Python program can provide a thumbnail generating service for Flash applets. This is useful for experiments involving new user interfaces for managing documents. Roger has contributed ActionScript 3 classes that interface to the service.

The thumbnails are generated using IExtractImage, which is part of the Windows XP API. Windows XP uses IExtractImage to produce the thumbnail images that appear in the default XP file browser. (Earlier versions of Windows lack this feature.) The link to Flash uses Local Connection, which is implemented using some public domain C code written by Philippe Elsass. The two parts of the program are turned into Python methods using SWIG.

Build instructions

Unfortunately, due to software incompatibilities, you can only use a Python extension that was compiled with the same version of Visual Studio as Python itself. Therefore, you should download the Python source and compile it yourself before you compile this extension. Then the two programs will match. For this reason, I am not distributing the binary version of this program.

Compile Python 2.5 (or later) using Visual Studio. Then unzip the thumbnail software (below). Edit the "build_extension.bat" script, and set the correct location of the newly compiled python.exe. Then run "build_extension.bat" in a Command Prompt window.

Usage example

The component parts of the module (once compiled) are:

  • api.py - Python container. This is what you should import.
  • _features.pyd - Code written in C. (No need to import this directly.)
  • features.py - C/Python wrapper. (No need to import this directly.)

The other files in the package demonstrate how the module works:

  • demo.py - Demo program written in Python
  • client.fla - Local connection demo
  • client.swf - Local connection demo
  • demo.png - A thumbnail is made of this image

When you run demo.py (using your own python.exe), it should

  1. create "thumbnail.jpg" from "demo.png"
  2. wait for a LocalConnection (forever).

You can interrupt this with control-C, closing the window, etc. However, if you open client.swf in a web browser, you get a text entry box. If you type text into that box and press the send button, it should (1) be received by demo.py, which (2) prints a message and (3) echoes the message back to client.swf, which should display "You said: " followed by whatever you typed. client.swf is from http://osflash.org/localconnection.

API

The following functions are in the api.py module:

  • Thumbnail(source_file, dest_file, image_size)

    A function for making thumbnails. Returns True on success. False is returned if a thumbnail couldn't be made for that particular type of file.

    This function might also raise an exception. IOError will be raised if you try to Thumbnail a file that does not exist, or tell Thumbnail to save somewhere that can't be written. SeriousProblem is raised if thumbnails can't be made at all. (This happens on Windows 2000.)

  • Send_Message(msg_text)

    Add a message to the outgoing queue. The message must be a string. The message is never sent until LocalConn_Poll is called. You can have lots of messages in the outgoing queue at once. All of them are sent in order by calls to LocalConn_Poll.

  • Receive_Message()

    Returns the next message in the incoming queue (a string), or None if no messages are waiting. You must call LocalConn_Poll to obtain new messages because Receive_Message only checks the queue.

  • LocalConn_Poll()

    Polls the local connection interface for new messages, and sends messages in the outgoing queue. Your program should call this function at regular intervals. It may raise the SeriousProblem exception if an error occurs.

  • SeriousProblem

    A custom exception used by Thumbnail and LocalConn_Poll.

In testing, I have only seen SeriousProblem occur when trying to make thumbnails on a Windows 2000 machine. (This doesn't work.) SeriousProblem might also be triggered by some errors relating to local connections.

Files

  • thumbnail-src-0.1.zip - Source package; compiles with Microsoft Visual Studio 2005 and Python 2.5. Other versions may work. You must build your own version of Python using Visual Studio first.
  • thumbnail_as3.zip - ActionScript 3 interface classes for the Thumbnail module.