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 depends on and is bundled with SZ and ZST 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 software package that includes XRHLIB, SZ 2.1.9 and the ZST (Zstandard) source code that is bundled with SZ 2.1.9. To download XRHLIB, right click on the following xrhlib.zip link, and select Save Link As :

xrhlib.zip

1,274,743 bytes (1.2 MB) SHA

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

xrhlib
xrhlib/sz-2.1.9/sz/src
xrhlib/sz-2.1.9/sz/zstd/common
xrhlib/sz-2.1.9/sz/zstd/compress
xrhlib/sz-2.1.9/sz/zstd/decompress
xrhlib/sz-2.1.9/sz/zstd/dictBuilder

We show how to do that with Code Blocks with 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. 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 1:  New Code Blocks MinGW64 C++ project has one source code file.

Next, add all the “.c” files in the xrhlib directory into the project, by selecting Project > Add Files..., then navigating to the xrhlib directory, and selecting the “.c” files in that directory, then pressing Open. (Note: To select multiple “.c” files at once, click on a “.c” file, then while holding the Ctrl key, click on each of the rest of the “.c” files in the directory).

Only add “.c” files into the project, not “.h” or fortran files.

The project workspace will now have a new directory called xrhlib with those files in it:


Figure 2:  Source code files from xrhlib directory added into the project.

Continue doing this for all of the directories listed above. The sz/src directory has many sz/src “.c” files which can be removed later. You can figure out which sz/src “.c” files are not needed later. For now, just add all the “.c” files in sz/src to make it easier to get started.

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.

After adding the “.c” files to the project, we need to link to ZLIB.  ZLIB will not be needed in the future, but it is needed now to be able to export to Gimp, which will be discussed below.

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.

Before proceeding to write programs that read XRH files, you will need an XRH file to work with. For this example, download ClassroomSZ.xrh into the console app project directory (right click on the following ClassroomSZ.xrh link and select Save Link As):


Sample Files

Classroom

ClassroomSZ.xrh

3,507,036 bytes (3.34 MB) SHA
32-bit floating point samples (3 samples per pixel)
Image dimensions: 3200 × 1800 pixels
Error Bound Mode: Absolute
Error Bounds: Y = 1E-3, CbCr = 1E-2
Scene model credit: NovaZeeke/BenediktBitterli
Original (lossless): ClassroomZebra.xrh (49 MB) SHA

Description: Japanese classroom with lights turned off.
License: ClassroomSZ.xrh and ClassroomZebra.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.

Veach, Ajar

VeachAjarSZ.xrh

9,291,188 bytes (8.86 MB) SHA
32-bit floating point samples (3 samples per pixel)
Image dimensions: 3200 × 1800 pixels
Error Bound Mode: Absolute
Error Bounds: Y = 1E-3, CbCr = 5E-3
Scene model credit: Benedikt Bitterli
Picture on wall credit: Calle Eklund
Original (lossless): VeachAjarZebra.xrh (50 MB) SHA

Description:  New recreation by Benedikt Bitterli of a scene model originally created and displayed by Eric Veach on Iris workstations. We replaced the picture on the wall with a photograph by Calle Eklund of a lake in Sweden.
License: VeachAjarSZ.xrh and VeachAjarZebra.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.

Gimp Support

We will show how to export ClassroomSZ.xrh to the Gimp image processing program. The following source code snippets specified for copy/pasting may be freely used without restriction, provided ‘as is’ without any express or implied warranty; In no event will the authors, publishers or anyone associated thereof be held liable for any damages arising from the use of these source code snippets.

Make sure ClassroomSZ.xrh is in the console app directory. Enter (copy/paste) these include statements into main.cpp before the main() function:

#include "xrhlib/xrhlib.h"     
#include "xrhlib/xrhlib_gimp.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,
  "ClassroomSZ.xrh")) return -1;        
printf("XRH SZ file loaded.\n");        

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

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

That will create a file called ClassroomSZ.exr that Gimp can import. To open that file, in Gimp select File > Open…, then navigate to the folder the file is in, select the file, and click Open.

With the file opened in Gimp, press the Plus/Minus keys on the numeric pad of your computer keyboard to zoom in and out.

Note: When working with floating point data, 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.

Figure 3:  Screen shot of a floating point image opened for editing in Gimp. Click to view larger. The image is displayed with limited dynamic range because it is displayed on a monitor. Nevertheless, Gimp can edit the underlying floating point data.

While editing an extended range image in Gimp, the floating point sample values under the screen pointer are displayed in the Pointer Information window. For example, hovering over shiny metal in the image display window shows that the underlying samples are brighter than 1.0:


Figure 4:  Hovering the screen pointer over shiny metal in the image display window on the left shows it has RGB values greater than 1.0.  In this example, each R, G and B sample value is greater than 15, listed in the Pointer Information window on the right.

If the Pointer Information window is not showing, activate it by selecting Windows > Dockable Dialogs > Pointer, or by clicking on the plus sign of any tabbed dialog and selecting Add Tab > Pointer.


Return to Computer Science

Return to Alternative University

Copyright © 2020 Arc Math Software, All rights reserved
Arc Math Software, P.O. Box 221190, Sacramento CA 95822 USA   Contact
2020–Oct–26  04:45  UTC