Computer Science

XRHLIB is free C language source code for reading and writing XRH o files. XRHLIB is released under the ZLIB-style license, and is bundled with ZST, SZ and ZFP which are released under the BSD license. This web page gives instructions on how to build the XRHLIB software, and provides sample images.

First, download the XRHLIB source code package that includes XRHLIB, ZST, SZ and ZFP:

Create a new C/C++ project, copy the xrhlib-2.0.0 directory tree out of xrhlib200.zip to create an xrhlib-2.0.0 subdirectory off the new project directory, and include into the project all of the “.c” files in the following directories:

We show how to do that with CodeBlocks/MinGW64 on Microsoft Windows (and with Visual Studio). In this example, we will use C++. Any other programming language that can call C functions could be used, including C itself.

In Code Blocks (or Visual Studio), create a new Console App project. Select C++ as the project type. When asked to select the compiler in Code Blocks, this example uses built-in MinGW64 that comes with Code Blocks (referred to as GCC):

After the project opens, in the Projects > Workspace window of Code Blocks, click on the plus sign on the left of Sources to show the source code files for the project, which so far is only one source file named main.cpp:

Next we will add the xrhlib.c file from the xrhlib-2.0.0 directory into the project. Note: We will be adding only “.c” files into the project, not “.h” files. We will add the xrhlib.c file into the project, not the xrhlib.h file.

To add the xrhlib.c file to the project, select Project > Add Files..., navigate to the xrhlib-2.0.0 directory, select the “xrhlib.c” file in that directory (not “xrhlib.h”), then press Open.

The project workspace will now have a new directory called xrhlib-2.0.0 with that file in it:

Now we will add the “.c” files for SZMOD compression to the project. First, select Project > Add Files..., and navigate to

xrhlib-2.0.0/szmod/src

then press Ctrl-A (while holding down the Ctrl key, press the A key), which selects all the files in that directory. Then press Open.

All the files in that directory are “.c” files. That made it easy to select them. We just selected them all. Note: Not all those files are actually needed. You can figure out which szmod/src “.c” files are not needed later.

Continue doing this for the zstlib directories listed above. Those directories will have some “.h” files. Do not add the “.h” files to the project. Only add the “.c” files to the project.

To select multiple “.c” files in the Open dialog, click on a “.c” file, then hold down the Ctrl key and click on more “.c” files. Remember, add only the “.c” files.

If using Visual Studio (VS) instead of Code Blocks, you can add files to the project by selecting Project > Add Existing Item. To view the project workspace in VS, select View > Solution Explorer. And note that folders are not automatically created in the VS worksapce like in Code Blocks, rather you need to create folders in the workspace view, by right clicking on Source Files (or subdirectories thereof) and selecting Add > New Filter. Create the new filter (workspace folder) first, then with that filter highlighted, select Project > Add Existing Item, to add “.c” files to that folder. You can add multiple files at a time, like in Code Blocks.

Before proceeding to write programs that read XRH files, you will need an XRH file to work with. For this example, download the Nova Zeeke Classroom file:

Make sure NovaZeekeClassroomSZ.xrh is in the console app directory. Enter (copy/paste) this include statement into main.cpp before the main() function:

Enter (copy/paste) these declarations into the main() function:

And enter (copy/paste) these source code lines into the main() function after the declarations:

This loads the Red, Green and Blue channels of floating point samples, and image width and height. The channels are loaded into float arrays that XRHLIB allocates with malloc(). Remember to free the memory later after using it:

Following is the function prototype for that function to load an XRH file:

In this example, we passed zero to the two mask arguments, to avoid loading the masks. Examples using masks are provided in the Gimp section below.

Use of ZFP compression is optional. To implement ZFP support in XRHLIB, uncomment the ZFP include statement in xrhlib.c:

and add (to the project) the “.c” files in this directory:

Only add the “.c” files that are in that directory, not “.h” files and not any files that are in subdirectories of that directory.

We will show how to export Nova Zeeke Classroom to Gimp. Gimp now supports 32 bit floating point channels, but requires the EXR motion pictures format. XRHLIB includes optional source code to export to Gimp with EXR. We explain how to do that now.

First add the xrhlib_gimp.c file into the project. That file is in the directory called “optional”, which is a subdirectory of the xrhlib-2.0.0 directory.

Only add the “xrhlib_gimp.c” file into the project (not the “xrhlib_gimp.h” file).

After adding xrhlib_gimp.c to the project, we need to link to ZLIB, because the EXR format Gimp uses requires ZLib.

In Code Blocks, link to ZLIB by selecting Project > Build Options, then click on Linker Settings, and under Link Libraries click Add, then in the Add Library dialog window click the folder tool to navigate, then navigate to the MinGW64 library folder which is usually Program Files > CodeBlocks > MinGW > x86_64-w64-mingw32 > lib, and scroll down and select libz.a (near the end of the list), click Open, then when asked to keep as a Relative Path select NO, then click OK in the Add Library dialog window, then click OK at the bottom of the Project Build Options window.

If using VS instead of Code Blocks, a separate ZLIB dll may need to be downloaded and linked to, since VS does not have ZLIB built in like Code Blocks does. Many VS users use ZLIB, so public information is available about how to do that for VS.

Make sure NovaZeekeClassroomSZ.xrh is in the console app directory. Enter this include statement into main.cpp before main():

Add these two declarations in main():

And replace the two zero arguments with those variables (depicted in blue) in the function to load an XRH file:

This will load the XRH file including the 5 masks of the file. The masks are stored as bit planes of ppn_masks, which XRHLIB allocates with malloc and like other channels must be freed later after use:

To export this floating point image with its first mask to Gimp, enter this source code:

Do that again to export the image with its second mask as a second EXR file:

The XRH file of this example has 5 masks. The first mask shows which pixels have luminance greater than 1.0, the second mask which pixels have luminance greater than 2.0, etc., up to the fifth mask which shows which pixels have luminance above 5.0.

Before we load floating point image files into Gimp, it is useful to allow Gimp to open large files. To do that, in Gimp select Edit > Preferences > System Resources, and make sure Maximum New Image Size is at least 1 Gigabyte.

Open the first file (Classroom1.exr) in Gimp. Make sure the Channels dialog is open, by selecting Windows > Dockable Dialogs > Channels. In the Channels dialog, click on the Eye of the Alpha channel to turn that channel off and on.

When the Alpha channel is on, only the pixels that are brighter than 1.0 are shown. That includes some of the windows, metal of the chairs, and the leading edge of the flag that faces windows.

Switch back and forth between having the Alpha channel off and on to see where the bright areas are relative to the rest of the image.

Load the second EXR file, Classroom2, and switch back and forth between the images by clicking on their respective buttons above the images. In the second image, none of the windows are brigher than 2.0, less of the leading edge of the flag is brighter and less metal is brighter though still many corners are.

Linear RGB values of pixels under the screen pointer are reported in the Pointer window (select Windows > Dockable Dialogs > Pointer).

To zoom, press the Plus/Minus keys on the numeric keypad of the computer keyboard.