~wahn/rs-pbrt

ref: a4415af80934ee84d62b76e5e536449ed582013e rs-pbrt/docs/source/getting_started.rst -rw-r--r-- 7.4 KiB
a4415af8Jan Walter Prepare v0.9.7 release. 2 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
===============
Getting Started
===============

Get Rust
========

First `install Rust`_. To keep it up to date use `rustup`_:

.. code:: shell

          rustup update

Compiling rs_pbrt
=================

Cloning the repository
----------------------

There are three repositories you can get the **Rust source code** from:

1. `sourcehut repository`_
2. `GitHub repository`_
3. `Codeberg repository`_

All three should be exactly the same, but reported issues etc. might differ.

sourcehut
.........

.. code:: shell

          # read-only
          git clone https://git.sr.ht/~wahn/rs-pbrt
          # read/write
          git clone git@git.sr.ht:~wahn/rs-pbrt

GitHub
......

.. code:: shell

          # using SSH
          git clone git@github.com:wahn/rs_pbrt.git
          # or using HTTPS
          git clone https://github.com/wahn/rs_pbrt.git

Codeberg
........

.. code:: shell

          # using SSH
          git clone codeberg@codeberg.org:wahn/rs_pbrt.git
          # or using HTTPS
          git clone https://codeberg.org/wahn/rs_pbrt.git

Use Cargo to compile executables
--------------------------------

.. code:: shell

          # enter repository
          cd rs_pbrt
          # compile without OpenEXR support
          cargo test --release --no-default-features
          # compile executable rs_pbrt (and run it to see options)
          cargo run --release --no-default-features

For a **debug** version compile without the ``--release`` option.

.. code:: shell

          # compile without OpenEXR support
          cargo test --no-default-features
          # compile executable rs_pbrt (and run it to see options)
          cargo run --no-default-features

For more information about **Cargo**, check out `its documentation`_.

The executables can be found in either the **release** or the
**debug** target directory:

.. code:: shell

          # release
          ls ./target/release
          # debug
          ls ./target/debug

Create a local copy of the documentation
========================================

.. code:: shell

          # no OpenEXR support
          cargo doc --no-default-features

Use your favourite `web browser`_ to open the local (Rust source code)
documentation:

.. code:: shell

          firefox target/doc/rs_pbrt/index.html

You can also find the `official documentation`_ (of the latest
release) on the ``rs_pbrt`` web site.

Running the renderer
====================

Without arguments (or by providing the ``-h`` or ``--help`` option)
you get a simple **usage** message of the main executable ``rs_pbrt``:

.. code:: shell

          # relative path to executable rs_pbrt (assuming release build)
          ./target/release/rs_pbrt --help
          # output
          rs_pbrt 0.9.7
          Parse a PBRT scene file (extension .pbrt) and render it

          USAGE:
              rs_pbrt [OPTIONS] <path>

          FLAGS:
              -h, --help       Prints help information
              -V, --version    Prints version information

          OPTIONS:
                  --cropx0 <cropx0>            Specify an image crop window <x0 x1 y0 y1> [default: 0.0]
                  --cropx1 <cropx1>            Specify an image crop window <x0 x1 y0 y1> [default: 1.0]
                  --cropy0 <cropy0>            Specify an image crop window <x0 x1 y0 y1> [default: 0.0]
                  --cropy1 <cropy1>            Specify an image crop window <x0 x1 y0 y1> [default: 1.0]
              -i, --integrator <integrator>    ao, directlighting, whitted, path, bdpt, mlt, sppm, volpath
              -t, --nthreads <nthreads>        use specified number of threads for rendering [default: 0]
              -s, --samples <samples>          pixel samples [default: 0]

          ARGS:
              <path>    The path to the file to read

The **version** can be checked by:

.. code:: shell

          # print version number
          ./target/release/rs_pbrt --version
          # output
          rs_pbrt 0.9.7

Your first rendered image
=========================

By specifing an input file (in this case ``cornell_box.pbrt``) you can
render a `PNG`_ image (currently always being called ``pbrt.png``):

.. code:: shell

          # specifing an input file
          ./target/release/rs_pbrt ~/git/gitlab/rs-pbrt-test-scenes/pbrt/cornell_box/cornell_box.pbrt
          # output
          pbrt version 0.9.7 (unknown) [Detected 4 cores]
          Copyright (c) 2016-2022 Jan Douglas Bert Walter.
          Rust code based on C++ code by Matt Pharr, Greg Humphreys, and Wenzel Jakob.
          Film "image"
            "integer xresolution" [500]
            "integer yresolution" [500]
          Sampler "sobol"
            "integer pixelsamples" [8]
          Integrator "path"
          Integrator "path"
          Rendering with 4 thread(s) ...
          1024 / 1024 [=======================================================================] 100.00 % 176.58/s
          Writing image "pbrt.png" with bounds Bounds2i { p_min: Point2i { x: 0, y: 0 }, p_max: Point2i { x: 500, y: 500 } }

The resulting image should look like this:

.. image:: cornell_box_8_pixelsamples.png

If you modify the proper line in ``cornell_box.pbrt`` to use more
**pixel samples** you should end up with a less noisy image, but
rendering will take longer:

.. image:: cornell_box_256_pixelsamples.png

.. code:: diff

          diff --git a/assets/scenes/cornell_box.pbrt b/assets/scenes/cornell_box.pbrt
          index aa3a210..559e860 100644
          --- a/assets/scenes/cornell_box.pbrt
          +++ b/assets/scenes/cornell_box.pbrt
          @@ -10,7 +10,7 @@ Film "image"
             "integer yresolution" [ 500 ]
           ##  "integer outlierrejection_k" [ 10 ]
           ##Sampler "sobol"
          -Sampler "sobol" "integer pixelsamples" [8]
          +Sampler "sobol" "integer pixelsamples" [256]
           ##PixelFilter "blackmanharris"
           ##SurfaceIntegrator "bidirectional"
           ##Integrator "directlighting" "integer maxdepth" [10]


Instead of modifying the ``.pbrt`` file you can alternatively specify
the samples per pixel on the command line:

.. code:: shell

           ./target/release/rs_pbrt --samples 256 ~/git/gitlab/rs-pbrt-test-scenes/pbrt/cornell_box/cornell_box.pbrt

More scenes to render
=====================

Because ``rs_pbrt`` isn't 100% compatible to the C++ counter part
(yet) I collect ``.pbrt`` `scene files`_ in a separate repository on
**GitLab**. Have a look at the `Wiki`_ there.

Just clone it to another location:

.. code:: shell

           # using SSH
           git clone git@gitlab.com:jdb-walter/rs-pbrt-test-scenes.git
           # or using HTTPS
           git clone https://gitlab.com/jdb-walter/rs-pbrt-test-scenes.git

That's it, for a quick start ... have fun rendering some of the
provided scenes!

.. image:: vw-van.png

.. _install Rust: https://www.rust-lang.org/tools/install
.. _rustup: https://github.com/rust-lang-nursery/rustup.rs
.. _sourcehut repository: https://git.sr.ht/~wahn/rs-pbrt
.. _GitHub repository: https://github.com/wahn/rs_pbrt
.. _Codeberg repository: https://codeberg.org/wahn/rs_pbrt
.. _its documentation: https://doc.rust-lang.org/cargo
.. _web browser: https://en.wikipedia.org/wiki/Web_browser
.. _official documentation: https://www.rs-pbrt.org/doc/crates/rs_pbrt/index.html
.. _PNG: https://en.wikipedia.org/wiki/Portable_Network_Graphics
.. _scene files: https://gitlab.com/jdb-walter/rs-pbrt-test-scenes
.. _Wiki: https://gitlab.com/jdb-walter/rs-pbrt-test-scenes/wikis/home