Home » Gallery » Tools

rayhunter 1.3.4

More sample images in rayhunter gallery.

rayhunter is a command-line program that takes a 3D model (like a VRML, X3D or Collada file) and renders an image that would be visible from given camera looking at given scene. Two ray-tracing algorithms may be used: deterministic (classic Whitted-style ray-tracer) and Monte Carlo path tracing.

You can take a look at the gallery of images rendered using rayhunter as a demonstration of rayhunter's capabilities.

Contents:

  1. Download
  2. Required command-line options
  3. Optional command-line options
  4. Some notes about 3d models handling by this ray-tracer
  5. Advantages over using ray-tracer built in view3dscene

1. Download

Download rayhunter:
Support us on Patreon

No installation is required. Just download and unpack these archives wherever you want, and run the program inside. The documentation (this web page) is also included inside (look in the documentation/ subdirectory) for offline viewing.

This is free/open-source software. Developers can download sources of this program. Or just get the code from GitHub.

2. Required command-line options

Basic syntax to call rayhunter is

rayhunter classic <recursion-depth> <image-width> <image-height> <input-filename> <output-filename>

or

rayhunter path <recursion-depth> <non-primary-samples-count> <image-width> <image-height> <input-filename> <output-filename>

3. Optional command-line options

Options below may be placed anywhere at command-line (before, between or after required options listed above).

--camera-pos <float> <float> <float> (short form -p)
--camera-dir <float> <float> <float> (short form -d)
--camera-up <float> <float> <float> (short form -u)

These options set camera position, looking direction and up vector. --camera-up-z is shortcut for --camera-up 0 0 1.

Initial camera settings are determined by

  1. These command-line parameters.
  2. First *Camera or *Viewpoint node in VRML file. Remember that placement of camera node in VRML file is important -- camera's properties are modified by current transformation of camera node.
  3. Default values (default VRML 1.0 perspective camera) :
    • camera-pos = 0 0 1,
    • camera-dir = 0 0 -1,
    • camera-up = 0 1 0,

Things above are given in descending priority. E.g. if you will use --camera-pos 1 2 3 parameter then starting camera position will be always 1 2 3. If you don't use --camera-pos parameter then program will try to find camera node in VRML file. If such node is present — we will use camera position specified there. If not — we will use default camera position (i.e. 0 0 1).

Notes:

  • If camera-dir and camera-up will not be orthogonal vector up will be corrected. camera-dir and camera-up vectors must not be parallel. In particular, they must not be zero-vectors. Lengths of camera-dir and camera-up are not important, dir vector is always scaled based on camera-radius when program starts.
  • Besides VRML/X3D, also Collada and 3DS can include camera information, so we can use it. Other 3D formats don't support camera information.

Note that you can use view3dscene to comfortably determine good values for these options — see Console -> Print rayhunter command-line to render this view menu item in view3dscene.

--view-angle-x <float>

Use perspective projection, with given field of view angle in horizontal direction. In degrees. Default is 60 degrees. Note: vertical angle will be automatically determined based on horizontal view angle and window width/height (unless you specify force-view-angle-y, see below).

--force-view-angle-y <float>

Use perspective projection, with given field of view angle in vertical direction. Normally camera vertical angle will be automatically derived from --view-angle-x and requested output <image-width> and <image-height>. You can use this parameter to force some other non-proportional camera vertical angle.

--ortho <float> <float> <float> <float>

Use orthographic projection, with given left, bottom, right, top dimensions. This makes previous --view-angle-x and --force-view-angle-y ignored (they are not sensible in orthographic projection). Note that order of arguments follows the X3D OrthoViewpoint specificication (and differs from typical OpenGL, like used by glOrtho).

--scene-bg-color <red> <green> <blue>

Sets scene background color. Each RGB color component is a float in the range [0; 1]. By default background is black.

--write-partial-rows <rows> <log-rows-file>

Always after generating <rows> rows, rayhunter will write the (partially finished) output image (to <output-filename>, i.e. to the same file where final image is supposed to be written). Additionally, each time when writing such partial image, rayhunter will write a file <log-rows-file> that will contain a single integer — the number of already finished rows.

This option has a couple of uses.

  1. First of all, obviously, it lets you view unfinished results of rayhunter, if you're not patient.
  2. This allows you to interrupt rayhunter process at any time and you will remain with a partially completed image. Then you can run rayhunter once again with --first-row option to finish rendering the image. You can look at <log-rows-file> to know how many rows are already finished.

    E.g. you can use such script:

      rayhunter ... --first-row `cat rows.log` --write-partial-rows 10 rows.log
    
    This way after doing every 10 rows, rayhunter will save it's partially finished work. And if you will interrupt, kill etc. rayhunter process, you will be able to just run this script once again and rayhunter will start rendering roughly at the point where it finished.
  3. If you want to render the image on more than one computer at the same time, you can easily run rayhunter on every computer with different --first-row argument and with appropriately small <rows> value for --write-partial-rows. When all processes will finish their work, you will only have to combine resulting images into one.

Note that very small <rows> value can slow down the rendering process. But usually it's not a significant slowdown, after all usually ray-tracing takes a lot of time and wasting a couple of additional seconds is not a problem.

Give value of 0 for <rows> to disable writing partial image and <log-rows-file> file. This is the default behavior.

Note about writing partial image: when writing partial image, any errors during write are reported as warnings and then ignored. This is handy is you will view the image with some other program while rayhunter process is running: there's always a small chance that rayhunter will write the partial image exactly when another program is trying to read it. Depending on your OS, in such case writing of the partial image file may fail. That's why errors when writing partial image are ignored and rayhunter will just proceed with rendering.

--r-roul-continue <float>

This option is meaningful only when you use path tracer. Argument is a float number in range [0; 1]. At each point on the path, if the specified <recursion-depth> is exceeded, Russian-roulette is used to determine whether the path should terminate here. If random number from [0; 1] range is larger than argument given to this option, the path will terminate. In other words, argument for this option is the "continuation probability" — larger argument means that average path will be longer.

Usually too small values will produce a lot of noise, and too large values will make long rendering time.

However, note that there are some sensible scenarios when argument 1 for this option is sensible: if your scene is very very simple and you want all paths to terminate in a "natural" way (when ray will not hit anything in the scene). This will give you very accurate result (although some noise on the image will still be present, since the ray directions are still random), although rendering time will be really long even for simplest scenes.

When argument for this option is exactly 0, Russian-roulette will always lose. In other words, Russian-roulette will not be used at all. In this case <recursion-depth> value will work like for classic ray-tracer. But the result will always be biased, i.e. (slightly) incorrect, usually darker than it should be.

Default value is 0.5.

--primary-samples-count <count>

This option is meaningful only when you use path tracer. By default this is 1. Generally there is no sense in incrementing this too much. You can use here 10 or something like that to have anti-aliased image. If you want to just increment number of paths, usually it's wiser to increment <non-primary-samples-count>, this way you will slow down rendering by a little lesser factor.

--direct-illum-samples-count <count>

This option is meaningful only when you use path tracer. At each path point, the specified number of random rays directed towards light sources are checked. By default this is 1. You can increase this, which can bring good results if your scene has a complex light setting (many light sources, in different places etc.) Remember that you can also just increase number of paths (i.e. <non-primary-samples-count>), as this will also produce more checks for rays to light sources.

For educational purposed you can also set this to 0 — then you will get a naive path tracer that just hopes to hit some light sources with random rays. You will then need many many paths, even for simplest models, to get nice renderings.

--first-row <first-row-num>

If you will use this option with non-zero argument then <output-filename> must already exist. rayhunter will load the initial image from this file. Then the image will be resized, if needed, to <image-width> and <image-height>. Then rayhunter will start rendering, but not from the beginning: from the given <first-row-num> row number. Rendering results will be written on the image.

This way you can tell rayhunter to resume rendering that is already partially done. This is particularly handy in connection with --write-partial-rows option, see there for description.

Argument 0 (the default) for this options means that rendering should proceed normally, from the beginning of the image.

See also notes about command-line options for all my programs.

4. Some notes about 3d models handling by this ray-tracer

5. Advantages over using ray-tracer built in view3dscene

The same ray-tracer code as is used by rayhunter is also used inside view3dscene. While using ray-tracer from view3dscene is more comfortable, using command-line rayhunter has also some advantages: