Reads a Papyrus file and outputs a uniform AVS field and a structure containing the data present in the Image Header.
module ReadPapyrusFile <
build_dir="iac_proj/rd_papy",
src_file="rd_papy.c",
c_src_files="rd_pyutl.c",
out_hdr_file="gen.h",
#ifdef MSDOS
hdr_dirs="include/pc .",
link_files="lib/pc/papy3_32.lib"
#else
link_files="-lP -lJpglless -lJpglossy"
#endif
>
{
// Input: Papyrus filename
string+read+notify+req+IPort2 filename;
// External C code function
omethod+req+notify_inst papyrus_update<status=1> = "Read_Papyrus_File";
// Outputs: Currently busy, header information & image data
int+write+nonotify+OPort2 busy = 0;
Image_Header+write+nonotify+OPort2 header;
Image_Data+write+nonotify+OPort2 output_image;
};
The ReadPapyrusFile module reads a Papyrus file and outputs an uniform field containing the image data and a data structure containing the information stored in the image header. The uniform field is output as a Image_Data object. This object is derived from the Field_Unif module and and can hence be used in the exactly the same way. It can be directly connected to all the standard visualization modules. The information in the image header is output as an Image_Header object. This object simply contains references to 5 further objects which actually contain the primitive data values. See below for further information.
The ReadPapyrusFile module uses the Papyrus 3.5 toolkit to read Papyrus format files. The Papyrus data format is an extended form of the DICOM V3 data format that can store multiple 2D slices. This allows it to store an entire volume of data. The Papyrus 3.5 toolkit was developed by the Digital Imaging Unit of the University Hospital of Geneva. More information can be found at the the Papyrus website.
As this project internally uses the Papyrus library to read Papyrus files the Papyrus library must be installed correctly before compilation. This section details how the library should be compiled and installed.
To ease install on Windows the ReadPapyrus project comes with a pre-built binary version of the Papyrus library that is compiled for VC++. This binary will be automatically linked with Express when the ReadPapyrus project is compiled. Normally you will not need to do anything extra to the normal IAC installation process.
The only exception to this is if you want to build the Papyrus library yourself. In this case you will have to recompile the library from the source code available on the Papyrus web-site. This process is complicated by the fact that the available source code has a number of errors and the library has to be compiled different if it is to be included in AVS/Express.
Once the source code has been downloaded it should be extracted into a empty directory. Two sub-directories, jpglless and jpglossy, should have been created in this directory. Next the changes to the source code and makefiles have to be applied. This can be done by extracting the papy_win.zip file into the Papyrus toolkit directory. This should overwrite several C files and 3 makefiles. It will also add a new batch file, make_pap.bat. This batch file can be used to compile both the release and debug versions of the Papyrus library.
After the new build of the Papyrus library has been compiled the library file should be copied into your project directory. You should replace the iac_proj/rd_papy/lib/pc/papy3_32.lib file with the new papy3_32.lib file in either the Debug or Release directory. The release version should normally be used. However if you encounter problems then the debug version can be used to help solve those problems.
For all other platforms a pre-built library is not supplied with the ReadPapyrus project. This is because it would not be feasible for the IAC to maintain all the necessary versions. Instead the source code of the library must be downloaded from the Papyrus web-site and compiled for your system. Again this process is complicated by the fact that the available source code has a number of errors. It also does not have makefiles for Linux and Irix systems.
Once the source code has been downloaded it should be extracted into a empty directory. Several sub-directories should have been created in this directory. Next the changes to the source code and makefiles have to be applied. This can be done by extracting the papy_uniz.tar.gz file or papy_uniz.tar.Z file into the Papyrus source code directory. This should overwrite several C files and add several makefiles. Once this has been done the library can be compiled. This can be done by making the appropriate makefile. For instance on Irix the following command would be used:
make -f Makefile.sgN32
Finally the necessary header files and newly compiled libraries must be installed. This can be done in one of three ways; by installing them into your project directory, by installing them into your system directories or by altering your environment variables so that they point to the correct files.
If you intend to only use the Papyrus library in one project then it would probably be easiest to install the library into your project directory. This can be done by copying all the header files in the Papyrus include directory into the include sub-directory of your project directory. Similarly the libP.a, libJpglless.a and libJpglossy.a library must be copied from the $MACHINE/lib directory into the lib/$MACHINE sub-directory of your project directory. $MACHINE is the Express name of you system (i.e. sgN32, sg6).
If you intend to use the Papyrus library regularly it should be installed into the appropriate directories on your system. For example on some systems you would copy the header files into /usr/include and the library files into /usr/lib. Finally it is also possible to alter the appropriate environment variables so that your C compiler finds the appropriate header and library files and compiles Express using those.
&filename
The name of the file that should be read from. This parameter is of type string. The ReadPapyrusFile module checks that the supplied filename is valid and displays errors as appropriate. The filename string can contain either the full or relative path name of the file and can contain any of the AVS/Express environment variables (e.g. $XP_PATH<1>)
busy
This parameter indicates whether the ReadPapyrusFile module is currently busy processing data. The parameter is of type int. The parameter is set as appropriate by the ReadPapyrusFile module. It can be used by the user interface to indicate the current state of the module.
done
This parameter indicates whether the ReadDicomFile module has finished processing data. The parameter is of type int. The parameter is set to 1 when the ReadDicomFile module has completed correctly. If the module finishes with an error this parameter is not altered. The parameter can be used to trigger further processing of the read data.
This object contains the image data contained within the Papyrus file. The object is of type Image_Data. This object is derived from Field_Unif and can be used in the exactly the same way as a standard uniform field. The output data can have either 2 or 3 dimensions. If the specified Papyrus file only contains a single slice a 2D field will be created. If the file contains several slices than a 3D volume field will be created.
This object contains the header information contained within the Papyrus file. The object is of type Image_Header. This object contains references to 5 further objects. These objects actually contain the information read from the Papyrus file. Each of these sub-objects corresponds to the appropriate DICOM module. These modules are Patient, General_Study, General_Series, General_Equipment & Image_Series and contain the information shown below.
Further information on the purpose of these variables can be found in the Papyrus 3.5 user manual. This can be found at the Papyrus website.
The low-level ReadPapyrusFile module is used in the Functional Macro ReadPapyrusFunc. This functional macro is used in the User Macro read_papyrus. The read_papyrus macro also uses the ReadPapyrusUI UI macro, and the parameter blocks Image_Header and Image_Data.
Two example applications are provided. They both read in a Papyrus format file. The TilePapyrusEg example uses the tile_volume module to visualize the data whilst the IsosurfacePapyrusEg example uses the isosurface module. The IsosurfacePapyrusEg also uses a downsize module to reduce the amount of data to be visualized. A sample Papyrus file mipettra.pap is provided with the ReadPapyrus project.
iac_proj/rd_papy/rdpymods.v contains the V definitions of the ReadPapyrusFile module and the Image_Data, Image_Header, Patient, General_Study, General_Series, General_Equipment and Image_Series parameter blocks.
iac_proj/rd_papy/rdpymacs.v contains the V definitions of the ReadPapyrusUI UI macro, the ReadPapyrusFunc functional macro and the read_papyrus user macro.
iac_proj/rd_papy/rdpyapps.v contains the V definitions of the TilePapyrusEg and IsosurfacePapyrusEg example applications.
The low-level ReadPapyrusMods library containing the module ReadPapyrusFile does not specify a process. By default the express process will be used.
Fernand Alcatrao
Andrew Dodd, International AVS Centre James Perrin, Manchester Visualization Centre
International AVS Centre Manchester Visualization Centre Manchester Computing University of Manchester Oxford Road Manchester United Kingdom M13 9PL