Philosophy and background - Index

This document is intended both for (potential) users and for developers of the pfspd toolset. It takes 5 minutes to read it. Please do take this time to get acquainted with the underlaying ideas behind this set of utilities. This will avoid many questions and it will give you better understanding how to benefit most of this software.

The software components are made available under the (L)GPL as described by the individual packages.

This document explains the underlaying philosophy and guidelines for the set of pfspd tools. Pfspd is a Philips format for video data. This is intended as a set of general tools and interfaces to handle and manipulate such files easily.

Descriptions in this document in italics font refer to information that is site specific. Usually, the Nat. Lab. (the Philips research site in Eindhoven, Netherlands) is taken as an example.

The tools are developed along a "unix" style approach: simple straightforward utilities with one tool for a single purpose. These tools can be easily linked together via files, pipes or shell scripts to build powerful and more specific functions.

There are a few exceptions. E.g. the tool pv (pfspd viewer) accepts almost any pfspd format. In such cases, ease of use prevailed over code multiplication: one wants to be able to inspect every pfspd file easily.

Also, just like the "unix" approach, these tools generally do not print info, unless explicitly requested; they usually do their work silently.

Furthermore, the set of tools is developed along an "open source" philosophy. They are grown from our own requirements on the working floor, while at the same time the design is more generic to enable easy application by others and/or for related purposes. The programs have been enhanced by various group members, not working in a single project. This was done, while guarding the scope of each of the utilities, to prevent "a single tool for everything" which is in the end dying in its complexity and therefore not used by others.

Tools and utilities:

mtk	Generic makefile structure and project template.
cpfspd	Standard ANSI-C library for pfspd file access and common header manipulations.
pp	Pfspd file player (only MSWindows).
pv	Pfspd file viewer (all platforms).

All tools and libraries have some common properties; which are described below.

All software is written in pure ANSI-C or ANSI-C++ and is fully portable. Source code, as well as precompiled libraries/executables are distributed in every release. On all platforms gcc is used as the compiler. The table below shows operating system and compiler versions that were used to build our pre-compiled releases:

Platform	OS release	Compiler and version
HP	HP-UX B.11.11	gcc/g++ 3.2
SGI	IRIX64 6.5	gcc/g++ 3.2
Sun	SunOS 5.8	gcc/g++ 3.2
Linux	Linux 2.4.18	gcc/g++ 3.2
Cygwin	Cygwin 1.3.22	gcc/g++ 3.2 20020927 (prerelease)
MW Windows	Windows 2000	MS Visual C++ 6.0

Each utility can be activated via an "invoke script". This is a single script, which can be used on any platform. It automagically finds the correct executable. This way, there is no need to install the commands in a different way on different platforms. As example, one can make a symbolic link from the ~/bin directory to the invoke script (substitute $RELEASEPATH with the correct path and "utilname" with the name of the utility):

    ln -s $RELEASEPATH/utilname.sh ~/bin/utilname

Each release is accompanied with a Readme.txt file, which lists:

• Release number and date
• License info
• Purpose
• Usage of the program
• Supported file formats
• Other application specific information
• Wish list of requested changes
• Change history of the release:
  • Including previous releases, most recent at the top.
  • Distinguish "Bug fixes", "Functionality" and "Miscellaneous".

Most utilities have the following commonly used command options:

-ini file   read command line options from the specified ini-file
-help       prints usage information: options and expected arguments
-readme     prints the complete Readme.txt file
-version    prints version information
-v          verbose: prints at least the frame number being processed
-start #    start frame number of input file, numbering starts at 1
-len #      number of frames of the input to process

-frame #    the frame to process, numbering starts at 1

The version information consists of the program name, release number, magic number and also the release and magic numbers of underlaying libraries.

On any command argument that is the name of a pfspd file, one can supply a dash ("-"). On an input file, this refers to standard input, on an output file, it is standard output. This way, redirection of standard input and output is explicitly requested. This is slightly different from normal "unix" like conventions, since a pfspd file contains binary data; one needs to be careful not to direct such a file to the screen, but redirect it to/from a file or a pipe.

All text output is normally send to stderr (to avoid collision with data send through stdout). This is especially true for the verbose output. Only the help output is explicitely requested and therefore send to stdout. With help printing, there is no actual video processing. This way, the help output can be easily captured in a file etc.

All tools support at least Y only and YUV 4:2:2 multiplexed color formats. Some tools support all data formats that cpfspd can handle; among these are pfspd format conversion tools and viewers.

A release is numbered with three digits: Major.Minor.Micro (e.g. 1.0.0) A change in the number identifies:

• Major: incompatible command arguments or interface (for a library)
• Minor: extended functionality, major bug fixes
• Micro: minor bug fixes, new platform support

All source code is distributed with the releases. For bug tracking it is required that a release can be fully identified. For this, more than just the version number is used. Therefore both the release number and a magic number are compiled into the executable during the build process. The magic number is a checksum which depends on all source files. The open source philosophy allows application of this software on other platforms (e.g. TriMedia based systems). It also allows anyone to correct a bug and continue working without the need to go through formal bug report, development and release procedures. This way, a fast and flexible development process is supported.

All utilities have a common makefile system. This is called "mtk": make toolkit. Mtk takes care of multi platform support, and many compilation options, like debug, purify etc. It also takes care of the build process of a release kit. When mtk is used, the file "Makefile" only needs to define some make variables and includes a standard file "Make.mtk". The latter file takes care of automatic dependency generation, compilation and linking etc.

Before a program can be compiled, the environment needs to be known, e.g. the location of the libraries or tools to be used. As this depends on the site, this is not part of the "src" directory, but it is defined in a separate file called "Make.env". The script "setup.sh" creates such a Make.env file based on a site specific input file "Make.env.[site]". For some sites, such files are part of the release. If you reside at Philips Nat. Lab, please execute the script "setup.sh" to create the Make.env file. If you reside elsewhere, (e.g. at a site called "myplace") you should create a file "Make.env.myplace" containing the definitions at your site. Then, execute "setup.sh myplace" to use your definition file.

The make toolkit is a powerfull build system, that takes care of:

• Generation of the magic number from all source code
• Pass version number into the executable
• Pass the contents of the Readme.txt into the executable
• Compilation of both C and C++ code
• Handling of windows resouce files
• Automatic dependency generation at each build
• Many compilation options for purify, quantify, debugging etc.
• Separation of derived files for each platform
• TriMedia cross compilation and simulation
• Automatic generation of a release distribution kit

This software is initially developed in the research group "Video Processing and Visual Perception" in order to increase the ease of use of our own infrastructure. Later, other departments contributed.

All software is available "as is", without any guarantee or warranty and without formal support commitment.

In spite of this formal position, we take proud in delivering software that works and may be usefull for others. Therefore, we welcome feedback, comments, bug reports or missing functionality, as this helps the pfspd community to further improve its infrastucture.

Since the source code of the software is available, everyone is allowed to adapt the software for his own purpose, provided that the conditions of the (L)GPL are acknowledged. This is exactly the intention of this approach to stimulate creativity and cooperation. It is clear that the developers of this software can only respond to the software they have developed themselves, not to any modified and/or derived product. For this purpose, the version and magic number are used to distinguish original releases from derived work. Further, please, do realize that the development of this software is done mostly in our spare time and after-work hours.

We welcome suggestions and contributions to this toolsuite. We appreciate any feedback and invite others to contribute, provided that the the basic philosophy as described in this document is preserved. This is required to guard the properties of the toolset that made it a success:

• ease of use
• consistency (command line options, release policy)
• functional scope of each tool
• software quality
• platform independency
• flexibility
• etc.