On this page:
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.
All developers are expected to be familiar with two other documents: the developers guide and the cvs guideline.
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|
Cygwin is a unix-like environment on MSWindows PC's; the version number refers to the DLL version; we use a net release that was downloaded on April 25, 2003. When installing cygwin from the internet, one always downloads the most recent version of all tools. As a result, the cygwin configuration depends on the installation date. To avoid such dependency, we downloaded the full distribution and made it available of sourceforge. This way, we are sure to use an identical development environment.
In order to build the software for use on MS Windows PC's without the cygwin environment, the MS Visual C/C++ compiler is used. This is handled as a cross compiler in the makefile system; so developers execute this compiler in their cygwin shell. The libraries and executables generated this way can be used without cygwin on any MS Windows PC.
In addition to these platforms, cross compilation for TriMedia is supported by mtk. All pfspd tools are only compiled for compute servers and desktop workstations. There are no pre-compiled TriMedia libraries since compiled code is specific to a particular flavour of the processor.
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
Since the invoke script uses perl; it is assumed that the command "perl" is available in the command search path.
For people, residing at Nat. Lab. the perl command can be installed
with the command:
At Nat. Lab. all tools are installed
at /natlab/softtv/appls/utils. To install the most recent
versions of each tool, execute the following command:
This will create a symbolic link in your ~/bin directory
for each of the tools.
Each release is accompanied with a Readme.txt file, which lists:
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 processTools that only process a single image use option:
-frame # the frame to process, numbering starts at 1In addition to these, each utility has its own specific command options and arguments.
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:
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:
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 active feedback and participation of the pfspd community.
Therefore the pfspd-users mailing list is available:
email@example.com The pfspd-users list is intended for all normal interaction, both developers activities and user responses etc. You are more than welcome to subscribe.
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:
All developers are expected to adhere to the guidelines in the developers guide. A short, generic cvs introduction is described in the cvs guideline.
Authors: Bram Riemens Robert Jan Schutten Martijn van Balen Ralph Braspenning
This page is hosted by
Copyright (c) KONINKLIJKE PHILIPS ELECTRONICS N.V. 2000-2006
Philips Research Laboratories, Eindhoven, The Netherlands
CVS id: $Id: philosophy.html,v 1.3 2006/01/27 08:44:43 riemens Exp $