Alternative University

Computer Science

Raster Image Storage

Higher Precision Extended Range

XRHLIB Software

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 and SZ 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 and SZ:

xrhlib200.zip
(1.5 MB)

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:

xrhlib-2.0.0
xrhlib-2.0.0/szmod/src
xrhlib-2.0.0/zstlib/common
xrhlib-2.0.0/zstlib/compress
xrhlib-2.0.0/zstlib/decompress
xrhlib-2.0.0/zstlib/dictBuilder

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):

Figure 1:  Choosing MinGW64 C++ in Code Blocks.

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:


Figure 2:  New Code Blocks MinGW64 C++ project has one source code file.

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:


Figure 3:  Source code file from xrhlib-2.0.0 directory added into the project.

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.


Figure 4:  ZST source code files added into the project.

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:


Sample Files

Nova Zeeke Classroom

NovaZeekeClassroomSZ.xrh
(4.4 MB)

32-bit floating point samples (per channel)
Image dimensions: 3200 × 1800 pixels
Compression Type: SZMOD
SZ Error Bound Mode: Absolute
SZ Error Bounds: Y = 1E-3, CbCr = 2E-3
Number of Masks: 5
Scene model credit: NovaZeeke/BenediktBitterli

Description: Japanese classroom with lights turned off.

Preview o


Veach, Ajar

VeachEklundSZ.xrh
(10.7 MB)

32-bit floating point samples (per channel)
Image dimensions: 3200 × 1800 pixels
Compression Type: SZMOD
Error Bound Mode: Absolute
Error Bounds: Y = 1E-3, CbCr = 2E-3
No Masks
Scene model credit: Benedikt Bitterli
Picture on wall credit: Calle Eklund

Description:  New recreation by Benedikt Bitterli of a scene model originally created and displayed by Eric Veach. We replaced picture on the wall in the model (before rendering) with a photograph by Calle Eklund of a lake in Sweden.

Preview o


XRH download files license:    
NovaZeekeClassroomSZ.xrh and VeachEklundSZ.xrh may be freely downloaded and redistributed on the condition that a link is provided identifying this web page as the original source of the file.

Loading a File

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

#include "xrhlib-2.0.0/xrhlib.h"

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

float * rChannel; 
float * gChannel; 
float * bChannel; 
int width, height;

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

printf("Loading XRH SZ file...\n");  
if (load_from_xrh_rgb_file(&rChannel,
      &gChannel, &bChannel,       
      &width, &height, 0, 0,      
      "NovaZeekeClassroomSZ.xrh"))
return -1;  
printf("XRH SZ file loaded.\n\n");   

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:

free(rChannel);
free(gChannel);
free(bChannel);

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

// Read an XRH file                            
// Returns: zero = success, nonzero = failed. 
int load_from_xrh_rgb_file (float ** rChannel,
    float ** gChannel, float ** bChannel, 
    int * image_width, int * image_height,
    unsigned int ** ppn_masks,            
    unsigned int * number_of_ppn_masks,   
    const char * fname);                  

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.


Gimp Support

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():

#include "xrhlib-2.0.0/optional/xrhlib_gimp.h"

Add these two declarations in main():

unsigned int * ppn_masks;        
unsigned int number_of_ppn_masks;

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

printf("Loading XRH SZ file...\n");    
if (load_from_xrh_rgb_file(&rChannel,  
      &gChannel, &bChannel, &width, &height,
      &ppn_masks, &number_of_ppn_masks      
      "NovaZeekeClassroomSZ.xrh")) return -1;
printf("XRH SZ file loaded.\n\n");     

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:

free(ppn_masks);

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

printf("Saving First EXR file...\n");
if (save_to_exrzip32_file (rChannel, 
gChannel, bChannel,          
ppn_masks, 1,                
width, height,               
"Classroom1.exr")) return -1;
printf("First EXR file saved.\n\n"); 

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

printf("Saving Second EXR file...\n");
if (save_to_exrzip32_file (rChannel, 
gChannel, bChannel,          
ppn_masks, 2,                
width, height,               
"Classroom2.exr")) return -1;
printf("Second EXR file saved.\n\n"); 

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.

Figure 5:  Channels in Gimp. Click on the Eye to the left of a 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.


Return to Computer Science

Return to Alternative University

Copyright © 2021 Arc Math Software, All rights reserved
Arc Math Software, P.O. Box 221190, Sacramento CA 95822 USA   Contact
2021–Sep–22  20:54  UTC