PhotoNim: a CPU raytracer with BVH optimization based on kmeans clustering

Installation

PhotoNim is available and tested for Linux, MacOSX and Windows machines. To install it you can choose which approach you find the most fitting for you.

Prerequisites

To use PhotoNim you must have installed the Nim programming language (version 2.0 or higher) on your machine. To install the latest version on Unix you could run the following command:

curl https://nim-lang.org/choosenim/init.sh -sSf | sh

To install it on other OSs or to install previous versions, please refer to the Nim installation guide. Most of Nim installation already install the official Nim package manager Nimble. You can verify it by running:

which nimble

Installing from the repo

Choose the appropriate protocol (HTTPS or SSH) and clone the PhotoNim repository using the command

git clone https://github.com/Negrini085/PhotoNim.git    # for HTTPS
git clone git@github.com:Negrini085/PhotoNim.git        # for SSH

Installing from Tarball

Download the latest tarball from here and extract the tarball by running the command

tar -xzf PhotoNim-<version>.tar.gz

Installing using Nimble

Install PhotoNim using nimble by running

nimble install PhotoNim

Dependencies

PhotoNim depends on the following packages

• docopt >= 0.6
• nimPNG >= 0.3

which can be installed using Nimble

cd PhotoNim && nimble install

Other dependencies are used to generate animations:

• GNU Parallel
• FFmpeg

Usage

Here, you'll find a brief overview and basic examples to get you started. For a deeper dive into implementation details and more advanced usage scenarios, we recommend visiting the documentation site.

PhotoNim CLI

To use PhotoNim CLI you will first need to build the project executable and you can do it from the root directory in different ways:

• using nimble build command

  nimble build

• or explicitly compiling the source code

  nim c -d:release PhotoNim.nim

Both these commands will generate an executable, called PhotoNim and located in the root directory. You are now ready to use PhotoNim CLI: run the executable to see displayed the list of all commands

./PhotoNim

Usage:
    ./PhotoNim help [<command>]
    ./PhotoNim pfm2png <input> [<output>] [--a=<alpha> --g=<gamma> --lum=<avlum>]

The pfm2png command

Using the pfm2png command it is possible to convert an High Dynamic Range (HDR) image stored in a PFM (Portable Float Map) format to an Low Dynamic Range (LDR) in the widely-used PNG (Portable Network Graphics) format. This conversion process involves the application of a tone mapping algorithm, a technique used to compresses the dynamic range while preserving important visual details. This process makes the HDR image viewable on standard displays without losing the essence of its high dynamic range.

./PhotoNim help pfm2png

PhotoNim CLI `pfm2png` command:

Usage:
    ./PhotoNim pfm2png <input> [<output>] [--a=<alpha> --g=<gamma> --lum=<avlum>]

Options:
    <input>             Path to the HDRImage to be converted from PFM to PNG.
    <output>            Path to the LDRImage. [default: "input_dir/" & "input_name" & "alpha_gamma" & ".png"]
    --a=<alpha>         Color renormalization factor. [default: 0.18]
    --g=<gamma>         Gamma correction factor. [default: 1.0]
    --lum=<avlum>       Average image luminosity.

For this example we will use the memorial.pfm image and convert it with pfm2png:

wget https://www.pauldebevec.com/Research/HDR/memorial.pfm
./PhotoNim pfm2png memorial.pfm --a=0.30 --g=2.0

By varying the parameters alpha and gamma, you can produce visually different images without having to render them again:	-	$\alpha = 0.15$	$\alpha = 0.30$	$\alpha = 0.45$
$\gamma = 1.0$
$\gamma = 2.0$

The help command

You can use the help command to inspect a specific command helper screen and you can also use it without passing any command to see displayed the full PhotoNim CLI helper screen (this works in the same ways as passing (-h | --help) flags).

PhotoNim x Nimble tasks

You can try PhotoNim using Nimble by executing a specific nimble task from this list:

nimble tasks

build     Build the `PhotoNim` executable

demo      Run the `PhotoNim` demo

          Usage: 
                  nimble demo (OnOff|Flat|Path)

          Options:
                  persp | ortho          Camera kind: Perspective or Orthogonal
                  OnOff | Flat | Path    Renderer kind: OnOff (only shows hit), Flat (flat renderer), Path (path tracer)

demoAnim  Run the `PhotoNim` demo animation
examples  Run the `PhotoNim` examples
test      Run the `PhotoNim` tests
earth     Run the Earth animation

demo persp OnOff	demo persp Flat	demo persp Path

demoAnim	earth

PathTracer example

If you use the PathTracer renderer you can tune some parameters to better render your images:

proc newPathTracer*(nRays, depthLimit, rouletteLimit: SomeInteger): Renderer {.inline.} =
    Renderer(kind: rkPathTracer, nRays: nRays, depthLimit: depthLimit, rouletteLimit: rouletteLimit)

In the following example there are 16 images produced with no anti-aliasing or russian roulette, but all with a different number of rays fired per intersection and a certain number of bounces. On the y axis the numbers of rays fired are [1, 4, 9, 16], while on the x axis the bounces are [1, 2, 3, 4].

You can find many more examples in the examples folder.

Contributing

If you want to contribute to the project, you can open a pull requests or use the issue tracker to suggest any code implementations or report bugs. Any contributions are welcome!

License

The code is released under the terms of the GNU General Public License v3.0, see the LICENSE.