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.

Who should read this?


These pages are directed at new authors of sIBL-sets and developers intending to implement the format. The information here gets 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


Highslide JS
Close Move

Hollywood_Sign.ibl

[Header]
ICOfile = "HWSign3-Fence_Thumb.jpg"
Name = "Hollywood Sign"
Author = "Blochi"
Location = "Hollywood"
Comment = "Sunset and a clear sky, lots of blue dusk light"
GEOlat = 34.13404881298771
GEOlong = -118.32163274288177
Link = "http://www.hdrlabs.com/sibl/archive.html"
Date = "2007:03:08"
Time = "08:03:00"
Height = 2
North = 0

[Background]
BGfile = "HWSign3-Fence_TMap.jpg"
BGmap = 1
BGu = 0.000000
BGv = 0.000000
BGheight = 4000

[Enviroment]
EVfile = "HWSign3-Fence_Env.hdr"
EVmap = 1
EVu = 0.000000
EVv = 0.000000
EVheight = 180
EVmulti = 1.000000
EVgamma = 1.500000

[Reflection]
REFfile = "HWSign3-Fence_2k.hdr"
REFmap = 1
REFu = 0.000000
REFv = 0.000000
REFheight = 1024
REFmulti = 1.000000
REFgamma = 1.500000

[Sun]
SUNcolor = 254,206,169
SUNmulti = 1.000000
SUNu = 0.794000
SUNv = 0.476000
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. There may be additional files in these set folders, for example license agreements or large preview renders.

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.

2.0 Update (06-28-09)


This document was updated to include recent extensions: GPS data, date, time, link, multiple lights. These new parameters will be marked with [2.0] in this documentation.

The basic structure is based on the INI file format.
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
  • LIGHT ... multiple key lights [2.0 addition]

These parts are always upper-case. The second part of each parameter is lower case, and defines individual attributes. BGu means we're talking 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 correct
BGu=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 correct
Name = 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)

Comments [2.0]


Technically, everything that is not a known keyword, should just be ignored by loader scripts. However, to make things more clear, comment lines should be started with the ; symbol. Please note that previously we also used -- here, but decided later to adhere to the .ini file standard for better compatibility with ready-made parser libraries.

[Header]
ICOfile = "HWSign3-Fence_Thumb.jpg"
Name = "Hollywood Sign"
Author = "Blochi"
Location = "Hollywood"
Comment = "Sunset and a clear sky, lots of blue dusk light"
GEOlat = 34.13404881298771
GEOlong = -118.32163274288177
Link = "http://www.hdrlabs.com/sibl/archive.html"
Date = "2007:03:08"
Time = "08:03:00"
Height = 2
North = 0

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

[Header]

We are using an INI-file like syntax, so we need to name a group. Within each group the parameters may appear in any order.

ICOfile = "filename"

The ICOfile is the icon shown the browser. Typically that is a 128x128px JPEG.
It should represent the set, and should provide a quick visual identification. Ideally, it is a preview rendering of a test object (which can also be used to brand a commercial sIBL-collection).

Name = "string"

This is the Name of the set, so it can be sorted by name. Typically, it's the name of the folder containing the set.

Author = "string"

This is the name of the Author, who generated the HDR. For correct grouping it is important for authors to always use the same literal string.
 

Link = "string" [2.0]

An online reference, to imprint the source of the set. Can be any standard protocol, so an email link like "malto:contact@cool_hdr_vendor.com" is possible as well. The link doesn't have to be visible in the interface, it may also be used as active link target for the Author tag value.

Comment = "string"

This can help the user to find the right sIBL enviroment. It should be very short and to the point. Filtering functions also look at these comments, so they can also be used as comma-separated tag clouds.

Date = "yyyy:mm:dd" [2.0]

This is technically a string, that is aligned to the EXIF notation. Note, that this should be the shooting date, not the creation of the stitched panorama.

Time = "hh:mm:ss" [2.0]

Shooting time, that may be useful to search for specific lighting situations (i.e. sunset). The string format is aligned to EXIF notation, with a 24-hour clock.

Location = "string"

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. It's a good practice to use very coarse location names in identical spelling, so grouping makes sense.
 

GEOlat = FP number [2.0]

These are GPS coordinates in standard floating point notation. GEOlat refers to the latitude (vertical on the map) and ranges from -90 to 90. When authoring a set, the exact coordinates can be looked up on http://itouchmap.com/latlong.html or many other websites.

GEOlong = FP number [2.0]

Refers to the longitude (horizontal on the map) and ranges from -180 to 180.

North = FP number [2.0]

This is a horizontal marker of the the north direction in the panorama images, ranging from 0.0 to 1.0. It is used to align the entire lighting setup. Advanced implementations may also use it in conjunction with GPS data, date and time to setup a physical sky or physical sun system.

Height = FP number [2.0]

This is the capturing height of the panoramas, measured in meters from the lens center to the ground. In a lighting setup this height value helps to minimize projection distortion by having the correct distance between the ground plane and the lighting domes.
[Background]
BGfile = "HWSign3-Fence_TMap.jpg"
BGmap = 1
BGu = 0.0
BGv = 0.0
BGheight = 4000

BGfile = "filename"

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.
When authoring a sIBL-set you should put extra emphasize on tonemapping this image in a natural look.
 

BGmap = integer number

This tags the projectiontype of the image. It is an index number, that is defined as:
1. Spherical (a.k.a. Equirectangular or Lat/Long)
2. Cylindrical
3. Angular map (a.k.a. Lightprobe)
4. Rectangular BG projection

In practice, spherical maps (1) are most common and are supported by most importer scripts. Further information on mapping types is here.

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. mapsoffset
 

BGu = FP number

This is the offset value in Horizontal (u) direction, ranging from 0.0 to 1.0.
 

BGv = FP number

This is the offset value in Vertical (v) direction, ranging from 0.0 to 1.0. This parameter may be used to correctly place cropped skydome panoramas, that only do not include the empty area below the horizon.
 

BGheight = integer number

This is the pixel height of the image. It is useful for quick quality evaluation, without the necessity of actually opening the images first.
 
[Enviroment]
EVfile = "HWSign3-Fence_Env.hdr"
EVmap = 1
EVu = 0.0
EVv = 0.0
EVheight = 180
EVmulti = 1.0
EVgamma = 1.5

EVfile = "filename"

This is the name of the environment map. This image is the small and convoluted/blurred HDR, which delivers the diffuse lighting component. It may be in Radiance (.hdr) or OpenEXR (.exr) format. This image will not be directly visible in rendering, but only used for lighting the scene.
Authors should take extra care to have a useful default exposure set. That means, when opening the image in Picturenaut or Photoshop, the overall midtone values should look like the tonemapped background image. To adjust the default exposure, you can use Photoshop's Image-->Adustment-->Exposure function from the menu.
 

EVmap = projectiontype index

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

EVu, EVv = FP number

UV offset values, identical to the BGu and BGv parameters.
 

EVheight = Integer number

Pixel height of the hdr image.
 

EVmulti = FP number

This is the lighting multiplier. In most 3d applications this value will brighten the enviroment and may be used to finetune the exposure. However, for general compatibility it is advised to rather
 

EVgamma = FP number

This is an adjustment gamma value. Unless the host application works in a Linear Workflow, the HDR image will be adjusted with this Gamma value to match the LDR texture images. When authoring a set, it is important to set this value as low as possible, but as high as necessary to look similar to the tonemapped background. Best to use sIBL-Edit to eyeball the correct Gamma adjustment. Values between 1.4 and 2.0 are useful.
 
[Reflection]
--sorry for the giant Sunflare
REFfile = "HWSign3-Fence_2k.hdr"
REFmap = 1
REFu = 0.000000
REFv = 0.000000
REFheight = 1024
REFmulti = 1.000000
REFgamma = 1.500000

REFfile = "filename"

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 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.
The more generic setup is to map this reflection image on a large sphere, just like the background image. Make sure this sphere does not cast a shadow, has no influence on global illumination, and is invisible to the camera. It should only be visible to raytraced rays.
When authoring sIBL-sets, the same rules apply as for the environment image. The default exposure should be adjusted to match the background image as close as possible. Most important are the mid-tones, in color and brightness. Highlights may be significantly brighter than in the tonemapped background. After all, that's why we're using an HDRI for reflection...


All the other params are identical to the Environment image.

Comments [2.0]

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 with leading ; in the first line after the group name will be visible in sIBL-Edit. This is an image-specific note that doesn't show up anywhere else.
Note, that prior to version 2.0 we used -- as as leading characters, but switched to ; for better compatibility with existing INI-file parsing libraries.
[Sun]
SUNcolor = 254,206,169
SUNmulti = 1.000000
SUNu = 0.794000
SUNv = 0.476000

SUNcolor = 255,255,245

This defines the RGB value of the sunlight.
 

SUNmulti = FP number

This is the intensity value of the sun which defines the brigtness.
 

The sun position

sundir

Light positions are defined in relation to the background image, using UV coordinates. In a setup script these UVs are treated as spherical coordinates (theta, phi). More on the math required for implementations is in this thread.

SUNu = FP number

This value is the horizontal POSITION of the sun on the BG image
 

SUNv = FP number

This value is the vertical POSITION of the sun on the BG image
 
[Light1]
LIGHTname = "orange key"
LIGHTcolor = 249,220,189
LIGHTmulti = 0.8000
LIGHTu = 0.252000
LIGHTv = 0.856000

[Light2] LIGHTname = "blue kicker"
LIGHTcolor = 76,159,255
LIGHTmulti = 0.7000
LIGHTu = 0.668000
LIGHTv = 0.500000

The key light for the sun was a big success in the original sIBL standard. But in practice, it turned out to be not enough for some lighting environments.

Specifically, nightshots with multiple street lights, and artfully lit movie sets require multiple light sources. Anytime there are distinctive direct light sources, that cast a hard shadow in real life, this feature comes in handy. It's not intended to build complicated light rigs for faking radiosity (ala Lightgen or Lightbitch), but rather to complement radiosity with directional, shadow-casting, specular components.

[Light##]

To stick to the .ini file convention, we need unique section header names. That's why the light sources always start with "[Light", followed by an index number.

LIGHTname = "string"

When a setup script builds the light rig, this will be the interface name assigned to this light. It may descriptive, but should be kept short.

LIGHTcolor = 249,220,189

RGB triplet of the light color.

LIGHTmulti = FP number

This is the brightness of the light. When authoring you should take care of normalizing all lights - means all lights together add up to a useful value between 1.0 to 2.0 (representing 100% to 200%).

LIGHTu, LIGHTv = FP number


sundir

Light positions are defined in relation to the background image, using UV coordinates. In a setup script these UVs are treated as spherical coordinates (theta, phi). More on the math required for implementations is in this thread.

Open Standards

Syntax Conventions

The .IBL File Header

Background Image

Environment Image

Reflection Image

Sun Light

Multiple Lights [2.0]