How HDR images turn into sIBLings

One important cornerstone of the sIBL-System is the .ibl file format. It holds all the data necessary for browsing the collection and performing the lighting setup in a 3d application. It's the .ibl file, that smartens up a set of images, and turns them into a clearly defined lighting situation.

Developer Docs

These pages get you up to speed in understanding how an .ibl file is set up, how to read and write it. If you have any questions, drop by in the Developer Forum. Actually, when you plan to port sIBL to a new platform, drop by and say Hello anyway...

Prerequisites

As format we chose a text file in plain ASCII format over XML or database solutions. Reason is, that text files are the most common ground. They can be read and parsed with every scripting language, so a sIBL loader can be made easily for every 3d platform.

There is no master list where sIBL sets are registered. The sole presence of a folder with an .ibl file in it defines a sIBL set. All images needed for the setup should be in that folder as well, with their filename referenced in the .ibl file.

Keeping all the metadata separate from the images has the nice side effect, that any image format can be used. As long as the host application can read it, we're fine. We already have all the info we need in the .ibl file. Technically, all kinds of files could be linked into a sIBL set. Possible extensions could be an ambient soundbite from the environment, or a previously generated Lightgen/LightMapGen file.

We are using case-sensitive parameter names to make the parameter groups very clear. That defines a one-level hierarchy.

The groups are:

• BG … which stands for BackGround
• ENV … the enviroment image
• REF … reflection image
• SUN … a key light, usually the sun

These parts are always upper-case. The second part of each parameter is lower case, and defines individual attributes. BGu means we’re talkin about the BackGround image and the corresponding parameter for the u value (from the uv coordinates). Logically you can replace BG with ENV and get ENVu, which has the same meaning to the loader scripts.

Spaces:

BGu = 0.67 ...is correctBGu=0.67 …is wrong because it is missing spaces around the “=”
BGu =0.67 …is wrong ..one missing space
BGu = 0,67 …is wrong ..wrong decimal point. Name = "master of universe" ...is correctName = master of universe …is wrong ..missing ”
Name=”master of universe” …is also wrong ..missing spaces
Name = “master of universe = me” …is also wrong because of the “=” in the string

String, Float, Array:

The correct notation is really quite simple:

String = "this is a string"
Path = "c:\mypath\to something"
Float = 0.67
Integer = 33
Array = #("string" ,0.67 ,33)


[Header]
ICOfile = "backlotICON.jpg"
Name = "Studio Backlot"
Author = "Blochi"
Location = "Hollywood"
Comment = "super-bright day at the Gower Studios Backlot, giant sunflare..."


This is what a typical .ibl file header looks like.  

[Header]

We are using a ini file like syntax, so we need to name a group

ICOfile

The ICOfile is the icon shown the browser. Typically that is a 128x128px JPEG.

Name = “Studio Backlot”


This is the Name of the sdr, so it can be sorted by name.

Author = “Blochi”

This is the name of the Author, who generated the HDR. 

Location = “Hollywood”


To make it more easy to find the right locations we decided to add an Location parameter. That can be used for sorting and grouping within a set. 

Comment

Comment = “super-bright day at the Gower Studios Backlot, giant sunflare…”
This can help the user to find the right sIBL enviroment. It should be very short and to the point.

[Background]
BGfile = "HiResLL.jpg"
BGmap = 1
BGu = 0
BGv = 0
BGheight = 1024


BGfile

BGfile = “HiResLL.jpg”
This is the name of the Background image. This image is the very large jpg which will be the background in the rendering. Any regular image format is possible here, but JPG is certainly preferred for sharing over the internet. The image has to be in the same folder like the .ibl file itself, because this will be the relative path for an importer script. 

BGmap

BGmap = 1
This tags the projectiontype of the image. It is an index number, that is defined as:

1. Spherical
2. Cylindrical
3. Angular map
4. Rectangular BG projection

Offset parameters:

The reason to offset the BG/ENV/REF map is to have a clear north direction. It also allows remixing of sIBL sets by aligning the images without actually changing the pixel data.


 

BGu

BGu = 0 : This is the offset value in Horizontal (u) direction.  

BGv

BGv = 0 : This is the offset value in Vertical (v) direction. 

BGheight

BGheight = 1024 : This is the pixel height of the image. 

[Enviroment]
EVfile = "Diffuse10.hdr"
EVmap = 1
EVu = 0
EVv = 0
EVheight = 128
EVmulti = 1
EVgamma = 2.2


EVfile

EVfile = “Diffuse10.hdr”
This is the name of the enviroment image. This image is the small and convoluted/blurred HDR, which delivers the diffuse lighting component. This image will not be directly visible in rendering, but only used for lighting the scene. 

EVmap

EVmap = 1 …projectiontype index.

1. Spherical
2. Cylindrical
3. Angular map
4. Rectangular BG projection

EVu

EVu = 0 …offset in horizontal direction 

EVv

EVv = 0 …offset in vertical direction 

EVheight

EVheight = 128 …the pixel height of the hdr image 

EVmulti

EVmulti = 1

This is the lighting multiplier. In most 3d applications this value will brighten the enviroment. 

EVgamma

EVgamma = 2.2 
This is an adjustment gamma value. Unless the host application works in a Linear Workflow, the HDR will be adjusted with this Gamma to match the LDR texture images. 

[Reflection]
--sorry for the giant Sunflare
REFfile = "Refmap.hdr"
REFmap = 1
REFu = 0
REFv = 0
REFheight = 512 REFmulti = 1
REFgamma = 2.2
[Reflection]


REFfile

REFfile = “Refmap.hdr”

This points to the reflection map, which is a medium to high resolution HDR. Each 3d app has a different way to use this refmap. The most efficient way rendering-wise is inside the shader/material definition, but that is also the biggest pain to implement in a setup script. In MAX and MAYA it is currently limited to the materials of specific renderers. In Lightwave it unfortunately locks the objects to that particular scene, because the surfaces are saved within the LWO files.

All the other params are identical to the Environment image.

Comments

- -sorry for the giant Sunflare

Technically, everything that is not a keyword will just be ignored by the import scripts. So you could write whatever you want in there as plain text. However, a comment in the first line after the group name, with leading “- -” will be visible in sIBL-Edit. This is an image-specific note that doesn’t show up anywhere else.

[Sun]
--Additioal keylight ..ha!
SUNcolor = 255,255,245
SUNmulti = 1.6
SUNu = 0.73730
SUNv = 0.2578125


SUNcolor

SUNcolor = 255,255,245 : This defines the RGB value of the sunlight 

SUNmulti

SUNmulti = 1.6 : This is the intensity value of the sun which defines the brigtness. 

The Sunposition:


SUNu

SUNu = 0.73730 
This value is the horizontal POSITION of the sun on the BG image  

SUNv

SUNv = 0.2578125 
This value is the vertical POSITION of the sun on the BG image