Basic workflow

Printing a calibration chart

Photographing the calibration chart

Analyzing the calibration photos

Using VRLENS files in 3ds Max

Modifying lens profile data

Test correction utility

Arbitrary image correction/distortion utility



Search Keywords: .vrlens, V-Ray Lens file, Lens distortion


The lens analysis utility is the primary tool we supply for creating, previewing and editing of V-Ray lens files (*.vrlens), and contains a camera distortion analyzer, and a tool for correcting/distorting images. The VRLENS files can be used in 3ds Max, Maya etc. to provide realistic (measured) camera distortion (as opposed to the simple quadratic and cubic modes). The VRLENS format also supports zoom lenses, and the distortion parameters are linked to the focal length of the V-Ray Physical Camera. So, as the camera is zoomed in and out, the distortion parameters are automatically varied. This provides for a very realistic level of camera distortion simulation.

Basic Workflow

V-Ray lens files are created with the lens analysis utility, from a set of calibration images, photographed with the camera we want to measure. The general work-flow to produce a .VRLENS file for a particular camera (or a particular lens, if the lenses are interchangeable) is like this:


1. A calibration chart file is created by the utility, by selecting Analysis → Print Test Chart.... The utility outputs a PostScript (PS) formatted file. PS is a standard printer format, which can be easily converted to PDF via the ps2pdf utility (where applicable), or through an online service,


2. The calibration chart is printed to a sheet of paper, which is later photographed with the camera to be analyzed.


3. The image files from the camera are downloaded to a computer, where they are processed with the lens analysis utility: first, the photos are added (with the Add photos... button) to the lens profile and then analyzed (by clicking Analyze...).


4. The analyzed lens profile is saved (by selecting Profile → Save Profile) to disk. The .VRLENS file is ready to be used in 3ds Max, Maya, etc.

Printing a calibration chart

Print calibration chartFrom Analysis → Print Test Chart..., you should choose the aspect ratio of the camera (the image sensor, or that of the film gate). Using the correct ratio is beneficial for the accuracy of the method. Pressing the View... button will open the generated PS file in your default PostScript viewer (under Windows, you may need to install one –for example, the freeware GSview). You may also choose Save and convert the resulting PostScript file to PDF via the online service Both ways work. The chart is then to be printed to a sheet of clean white paper (size is not important, A4/Letter is OK). The grid lines need to be straight and free from defects (e.g., gaps, scratches and other irregularities). The illustration below shows an example calibration chart.


Calibration Grid

Photographing the calibration chart

The printed chart should be placed on a flat surface (wall, whiteboard) and pinned/taped/glued so that it is tense and without any bumps. The camera is to be placed directly in front of the chart, so the photograph to be taken contains the whole grid and just a bit of margin around it. Ideally, the four L-shaped corners should correspond to the corners of the photograph, but it doesn't hurt if they don't – it is fine as long as the whole grid is present and it doesn't come too close (e.g., a few pixels) of the image edges. The image center should be the black dot in the middle of the grid (the software is picky about that –only 1.5 boxes of offset is enough to have your image rejected). Pay great attention to the placement of the camera, it should be directly in front of the chart, and should point in a direction precisely perpendicular to the sheet. Even a small offset will introduce a perspective distortion, which greatly reduces the accuracy of the analysis (and therefore the software is extremely picky about this). Other things you should pay attention to:


Prime vs Zoom lenses


For a prime lens (i.e., a lens with fixed focal length), you only need one photograph of the calibration chart (but you are encouraged to take more shots as outlined in the hints; see below). For a zoom lens, you need several photographs at various zoom levels to build a complete profile of the lens (V-Ray will interpolate the distortion parameters during rendering, so a few photos are sufficient). This means you have to re-adjust the zooming of the lens, and the camera position several times and make a photograph at each focal length. These calibration photos should cover the entire lens range. The amount of calibration photos required for an accurate profile is somewhat variable and depends on the type of lens and your needs. A simple rule that you might find useful is to consider the zoom factor of the lens and use the same amount (rounded to integer) of calibration focal lengths. E.g., to profile a 28-135mm lens, which has a zoom factor of around 5 (135/28 ≈ 4.82 ≈ 5), you need 5 photos spaced evenly in the 28-135 range. On more wide-angle lenses, where the distortion is usually more prominent in the wide end of the zoom range (and the parameters there change faster), it makes more sense to concentrate more photos in the wide end. E.g., to cover a 18-55 lens, an example calibration progression could be 18mm, 24mm, 30mm, 40mm, 55mm.


In our tests at Chaos Software, creating lens profiles proved to be a tedious job, so you may find these hints useful:

Analyzing the calibration photos

The photos from the camera are transferred to the PC and processed with our lens analyzer tool. First, you should click on the Add Photos... button and import the calibration photos (for a zoom lens, the software may ask you to provide the focal lengths of the photographs if it isn't able to fetch them from image metadata. In this case you need to supply the correct focal length for each photo, as otherwise the profile will be incomplete). Then, click on the Analyze... button. As the images are processed, the utility will print out a statistic for each file: whether the analysis is successful or not, the error message if it fails, and a quality rating (like “perfect”, “very good”etc), based on the following performance criteria:



If the utility rejects photograph for a reason other than those four criteria, it may be helpful to turn on the detection-stage preview from Analysis → Show Detection Details and retry analysis. The preview may give you a hint why the detection finds the image difficult. After the analysis phase, the table describing the profile is populated with the detected distortion parameters of all successfully analyzed photos.


Note: if you followed the advice to take several redundant photos for each focal length, you can now either trim the profile manually by removing the inferior photos, as judged by the analyzer, or by using the automated merging tool accessible from Analysis → Consolidate Profile. “Consolidate profile” does not just remove the redundant photos –it averages the parameters of any calibration photos with the same focal length, so it is theoretically optimal. In either case, the final profile must have only a single set of parameters per each focal length. The table contains the following fields:



Note: The primary determining parameter is K1. All other parameters will be close to their default (“no-distortion”) values, but since the photographed grid can never be analyzed with absolute precision, some “noise” is expected to exist in the parameters. Further, when both K1 and K2 are nearly zero, the other parameters lose their significance and may fluctuate widely. In short, do not pay great attention if the parameters are not quite at their expected values –this doesn't mean there is a flaw in your lenses.

Using VRLENS profiles in 3ds Max

After you've produced acceptable calibration photos for each focal length and the analysis is done, you then need to save the profile to a file (Profile → Save Profile). We use the .vrlens extension for these files. Note that this is different from the .lens extension, which we also support in 3ds Max.


When saving the profile, the lens analysis utility may emit a warning if the current data is not suitable for production use –be it because of missing focal length information, or because there are several calibration photos for a single focal length, or because some of the images aren't analyzed. You should rectify these issues before creating a working .VRLENS file.


The VRLENS files are small and simple; they don't depend on other files or resources –using them in a DR should be straightforward.


To apply a VRLENS file for a measured camera distortion simulation in 3ds Max, you need to use the V-Ray Physical Camera. From the camera's settings, go to the “Distortion” rollout, use “Lens file”distortion type and click on Lens file to select it.

Modifying lens profile data

In the lens analysis utility:

Test correction utility

You can see an example of how an “un-distorted”image will look like by selecting one of the calibration images (just click on its name) and selecting Correction → Test correction. This will correct the calibration photo using the detected distortion parameters. You can switch between the corrected and original file for comparison.

Arbitrary image correction/distortion utility

You may correct or distort an array of arbitrary image files using Correction → Correct/Distort images.... Thus, a “perfect” image (e.g., from a render with no distortion whatsoever) can be distorted to match the characteristics of a measured camera, or, an image sequence shot by a real camera can be corrected so it matches the quality of a theoretical “perfect”camera.


This utility uses the complete lens profile, so, for zoom lenses, it calculates the needed distortion parameters per each image, in a manner similar to the way it is done in the V-Ray Physical camera during rendering. As a consequence of this, you need the focal lengths of each image that is going to be corrected or distorted, otherwise the parameters cannot be correctly interpolated. The utility would try to infer this from EXIF metadata; when that fails, it will present you with several choices, see below.




Here you select the images to be processed. Use Add file... to add individual files, or Add directory... for a whole directory, possibly including the full directory hierarchy below the selected one. Please note that the hierarchy will not be preserved in the output directory in that case. The output directory indicates where the processed files are to be stored, and you can select the direction of the process here. When you're all set up, click Process.




Here you can tweak various parameters regarding the process:


Resampling quality - you can choose the image re sampling function - choices are Nearest neighbour, Bilinear, or Area, which are a quality/speed tradeoff. Bilinear is fast and adequate for most purposes, so it is the default.


Use alternative resampling algorithm (slower) - This is only meaningful when using Nearest neighbour or Bilinear resampling and the processing direction is Undistort. Because of the mathematics involved in the distortion/undistortion formulas, it is much faster to transform an image in the “distort” direction. However, the “undistort”direction can still be achieved using the same internal machinery, but with inverting the image transfer function. This approach uses somewhat more memory and in some extreme cases could introduce image artifacts. This option should be mostly left unchecked; if the image quality is unacceptable, you may try to turn this option on and see if the quality improves.


Use XXX threads for processing - The image process is naturally multithreaded and will use all the processing power available in the system. Here you can tweak the number of working threads. Note: the amount of memory required for processing is proportional to the number of threads. With a lot of threads and when working with large images, your system may end up consuming all the memory available, and some of the images will not be processed in result. The situation can be alleviated by lowering the number of threads.


Low thread priority - use below-normal worker thread priority, giving more CPU time to other running tasks.


Output file format - select the output image format. By default, it is the same as the format of the source images


EXR settings, PNG settings, JPEG settings, TIFF settings - control various parameters used when writing the corresponding image types.


Correcting/distorting using a prime lens profile


With a profile of a prime lens, all images will be processed with the same set of distortion parameters, so no further complications can arise.


A zoom lens profile, but with distortion parameters from a single calibration photo


If you have several entries in the table (e.g., the profile of a zoom lens), click on the entry you want to use for correction/distortion. Then, at the “Options”tab of the Correct/Distort utility, another item will appear: Use selected profile settings and Use entire profile. If you select the former, then your images will be processed using the specified parameters only. As this situation is otherwise identical to the “Prime lens”scenario, no complications can arise either.


A full zoom lens profile


This is the most complex situation, where you have a full zoom lens profile, having different distortion parameters at various focal lengths, and you want to process an array of images, which can also have various focal lengths. So, before starting the actual image processing, the utility will first try to read the EXIF metadata from all input images. If some of the images don't have EXIF, or the focal length information isn't written in there, the utility will give you the following choices:



"Image_0001.exr" 35.6

"Image_0002.exr" 36.2

"Image_0003.exr" 38.0




"«file name»" «focal length»


with one file per line.


Correction/Distortion utility limitations: