Skip to content

Commit 41ee311

Browse files
bean-mhmbean-mhm
committed
Merge branch 'main' of https://github.com/bean-mhm/flim 
2 parents a97a421 + cd66499 commit 41ee311

File tree

1 file changed

+48
-41
lines changed

1 file changed

+48
-41
lines changed

‎README.md

Lines changed: 48 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,19 @@
22

33
## Introduction
44

5-
flim is an experimental film emulation transform that can be used for:
5+
**flim is an experimental film emulation transform** that can be used for:
66

77
1. Displaying Digital Open-Domain (HDR) Images
88
2. Color Grading
99
3. Post-Processing in Video Games and Shaders ("tone-mapping")
1010

11+
flim comes with 2 presets, but you can add your own presets with their custom parameters!
12+
- **default**: The default preset provides a generic look that works well on most images.
13+
- **gold**: Gives a tastier, more dramatic look.
14+
1115
## Eye Candy
1216

13-
- See comparisons between flim and other view transforms in the [releases](https://github.com/bean-mhm/flim/releases) section.
17+
- See comparisons between native sRGB, AgX, and flim's presets in the [releases](https://github.com/bean-mhm/flim/releases) section.
1418

1519
- You can find links to collections of OpenEXR image files for testing in [Useful Links](#useful-links).
1620

@@ -40,10 +44,12 @@ The code is structured in the following way:
4044

4145
| Script | Role | Uses |
4246
|---|---|---|
43-
| main.py | Generates a 3D LUT for flim | flim.py |
47+
| main.py | Compiles 3D LUTs for flim | flim.py |
4448
| flim.py | Transforms a given linear 3D LUT table | utils.py |
4549
| utils.py | Contains helper functions | - |
4650

51+
You can add new custom presets in `main.py`, or play with the film emulation chain in `flim.py`.
52+
4753
Here are the external libraries required to run the scripts:
4854

4955
- [Colour](https://www.colour-science.org/)
@@ -52,88 +58,89 @@ Here are the external libraries required to run the scripts:
5258

5359
- [Joblib](https://joblib.readthedocs.io/en/latest)
5460

55-
## Using the LUT
61+
## Using the LUTs
5662

5763
First, a few notes:
5864

59-
- flim's 3D LUT is designed to be used in an [OpenColorIO](https://opencolorio.org/) (OCIO) environment, but depending on your software and environment, you might be able to manually replicate the transforms in your custom pipeline.
65+
- flim's 3D LUTs are designed to be used in an [OpenColorIO](https://opencolorio.org/) (OCIO) environment, but depending on your software and environment, you might be able to manually replicate the transforms in your custom pipeline ([See Non-OCIO Guide below](#non-ocio-guide)).
6066

6167
- flim only supports the sRGB display format as of now.
6268

63-
If `main.py` runs successfully, you should see a file named `flim.spi3d` in the same directory. Alternatively, you can look up the latest LUT - no pun intended - in the [releases](https://github.com/bean-mhm/flim/releases) section, which may be outdated.
69+
If `main.py` runs successfully, you should see files named like `flim_X.spi3d` in the same directory. Alternatively, you can look up the latest LUTs in the [releases](https://github.com/bean-mhm/flim/releases) section.
6470

65-
The LUT's expected input and output formats are mentioned in the LUT comments at end of the file. The following is an example of the LUT comments (note that this might not match the latest version).
71+
The LUT comments contain most of the information you need. The following is an example of the LUT comments (note that this might not match the latest version).
6672

6773
```
6874
# -------------------------------------------------
6975
#
70-
# flim v0.5.0 - Bean's Filmic Transform
76+
# flim v0.6.1 - Bean's Filmic Transform
77+
#
78+
# Preset: default
79+
# URL: None
7180
#
7281
# LUT input is expected to be in Linear BT.709 I-D65 and gone through an AllocationTransform like the following:
7382
# !<AllocationTransform> {allocation: lg2, vars: [-11, 12, 0.00048828125]}
7483
#
7584
# Output will be in sRGB 2.2.
7685
#
77-
# Repo:
78-
# https://github.com/bean-mhm/flim
79-
#
80-
# Read more:
81-
# https://opencolorio.readthedocs.io/en/latest/guides/authoring/authoring.html#how-to-configure-colorspace-allocation
82-
#
83-
# -------------------------------------------------
86+
# Here's how you can add this to an OpenColorIO config:
8487
```
85-
86-
### OCIO Example
87-
88-
Here's an example of how you can add flim to an OCIO config:
89-
9088
```yaml
9189
colorspaces:
9290
- !<ColorSpace>
93-
name: flim
91+
name: flim (default)
9492
family: Image Formation
9593
equalitygroup: ""
9694
bitdepth: unknown
97-
description: flim - Bean's Filmic Transform
95+
description: flim v0.6.1 - https://github.com/bean-mhm/flim
9896
isdata: false
9997
allocation: uniform
10098
from_scene_reference: !<GroupTransform>
10199
children:
102-
- !<ColorSpaceTransform> {src: Linear CIE-XYZ I-E, dst: Linear BT.709 I-D65}
100+
- !<ColorSpaceTransform> {src: reference, dst: Linear BT.709 I-D65}
103101
- !<RangeTransform> {min_in_value: 0., min_out_value: 0.}
104102
- !<AllocationTransform> {allocation: lg2, vars: [-11, 12, 0.00048828125]}
105-
- !<FileTransform> {src: flim.spi3d, interpolation: linear}
103+
- !<FileTransform> {src: flim_default.spi3d, interpolation: linear}
104+
```
105+
```
106+
# Explanation:
107+
# 1. ColorSpaceTransform converts the input from the scene reference to Linear BT.709 I-D65. If this is named
108+
# differently in your config (for example Linear Rec.709), change the name manually.
109+
# 2. RangeTransform clips negative values. You might want to use a gamut compression algorithm before this step.
110+
# 3. AllocationTransform is for LUT compression, it takes the log2 of the RGB values and maps them from a
111+
# specified range (the first two values after 'vars') to [0, 1]. The third value is the offset applied to the
112+
# values before log2. This is done to keep the blacks.
113+
# 4. Lastly, the FileTransform references the 3D LUT and defines a trilinear interpolation method.
114+
#
115+
# Adding this as a view transform is pretty straightforward:
106116
```
107-
108-
1. Paying attention to the transforms, you will notice a `ColorSpaceTransform` from `Linear CIE-XYZ I-E` to `Linear BT.709 I-D65`. This is because the example OCIO config has its reference color space (the `reference` role) set to `Linear CIE-XYZ I-E`. If your config already uses `Linear BT.709 I-D65` (Linear Rec.709) as its reference this is not needed. If your config uses another color space as its reference, you should manually do a conversion to `Linear BT.709 I-D65`. You can get the conversion matrices using the [Colour](https://www.colour-science.org/) library.
109-
110-
2. Then, we have a `RangeTransform` which is there to eliminate negative values in out-of-gamut triplets. This is not the best approach as it might cause weird transitions in images that have been converted from a wider gamut and have a lot of negative values.
111-
112-
3. Next, we have an `AllocationTransform` which can be directly copied from the LUT comments. The `AllocationTransform` here takes the log2 of the tristimulus (RGB) values and maps them from the specified range (the first two values after `vars`) to the [0, 1] range. The third value in `vars` is the initial offset applied to the values. This is done to keep the blacks.
113-
114-
4. Finally, a `FileTransform` references the 3D LUT.
115-
116-
Here's an example of how you can add flim as a view transform to an OCIO config:
117-
118117
```yaml
119118
displays:
120119
sRGB:
121-
- !<View> {name: flim, colorspace: flim}
122-
...
120+
- !<View> {name: flim (default), colorspace: flim (default)}
121+
... (other view transforms here)
122+
```
123+
```
124+
#
125+
# Repo:
126+
# https://github.com/bean-mhm/flim
127+
#
128+
# Read more:
129+
# https://opencolorio.readthedocs.io/en/latest/guides/authoring/authoring.html#how-to-configure-colorspace-allocation
130+
#
131+
# -------------------------------------------------
123132
```
124-
125-
> `...` refers to the other view transforms in the config. `...` is generally used as a placeholder for the other parts of the code. I can't believe I had to mention this, but a friend was actually confused by it.
126133

127134
### Non-OCIO Guide
128135

129-
You can replicate the transforms farily easily in order to use flim's 3D LUT in your own pipeline without using OCIO. The following pseudo-code demonstrates the general process to transform a single RGB triplet (note that this might not match the latest version).
136+
You can replicate the transforms farily easily in order to use flim's 3D LUTs in your own pipeline without using OCIO. The following pseudo-code demonstrates the general process to transform a single RGB triplet (note that this might not match the latest version).
130137

131138
```py
132139
# Input RGB values (color space: Linear BT.709 I-D65)
133140
col = np.array([4.2, 0.23, 0.05])
134141

135142
# RangeTransform
136-
# (clip negative values, or use a custom gamut compression algorithm)
143+
# Clip negative values, or use a gamut compression algorithm.
137144
col = np.maximum(col, 0.0)
138145

139146
# AllocationTransform

0 commit comments

Comments
 (0)