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:
xrhlib200.zip
(1.4 MB)
Create a new C/C++ project, copy the
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):
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
To add the xrhlib.c file to the project, select Project > Add Files..., navigate to the
The project workspace will now have a new directory called
Now we will add the .c files for SZMOD compression to the project. First, select Project > Add Files..., and navigate to
then press
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
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:
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
Preview o
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
Preview o
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.
Use of ZFP compression is optional. To implement ZFP support in XRHLIB, uncomment the ZFP include statement in
#include "optional/zfp-develop/include/zfp.h"
and add (to the project) the .c files in this directory:
xrhlib-2.0.0/optional/zfp-develop/src
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
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.
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.