16.15. convert_pinhole_model

This tool can be used to approximately convert a pinhole model from one of the types listed in Section 20.1 or an optical bar model (Section 20.3) to any other pinhole model type. This can be convenient, for example, because the Brown-Conrady and Photometrix models provide a fast formula to undistort pixels, while the distortion operation is very slow, requiring a solver with multiple iterations using the undistortion formula at each step, which can make it time-consuming to run bundle adjustment and epipolar alignment during stereo. For other models, such as Tsai and Adjustable Tsai, the reverse is true, hence converting from the former to the latter models can be very convenient for performance reasons.

This program can also be used to convert a pinhole or optical bar model to a pinhole model with RPC lens distortion, which is a model where distortion is expressed as a ratio of polynomials. The RPC lens distortion model has the advantage that both the forward and reverse distortion calculation are approximated using RPC, hence both of these operations are fast, which can provide a large speedup when running stereo and bundle adjustment.

The degree of the RPC lens distortion can be specified via --rpc-degree. A smaller value is suggested to start with, as lower-degree polynomials may be easier to interpret.


convert_pinhole_model [options] <input image> <input camera> \
  -o <output camera>

Example (convert a camera model to the RPC type):

convert_pinhole_model input.jpg input.tsai --output-type RPC \
  --rpc-degree 2 -o output_rpc.tsai

Example (specify the image dimensions instead of the image, and convert to BrownConradyDistortion):

convert_pinhole_model input.tsai --output-type BrownConradyDistortion \
  --image-size "5000 4000" -o output.tsai

Command-line options for convert_pinhole_model:

-o, --output-file <filename>

Specify the output file. It is expected to have the .tsai extension.

--output-type <TsaiLensDistortion|BrownConradyDistortion|RPC (default: TsaiLensDistortion)>

The output model type.

--sample-spacing <number-of-pixels>

Pick one out of this many consecutive pixels to sample. If not specified, it will be auto-computed.

--rpc-degree <int (default: 3)>

The degree of the polynomials, if the output distortion model is RPC.

--camera-to-ground-dist <double (default: 0)>

The distance from the camera to the ground, in meters. This is necessary to convert an optical bar model to pinhole.

--image-size <”int int” (default: “”)>

Image width and height, specified as two numbers in quotes and separated by a space, unless the input image file is provided.

--threads <integer (default: 0)>

Select the number of threads to use for each process. If 0, use the value in ~/.vwrc.

--cache-size-mb <integer (default = 1024)>

Set the system cache size, in MB.

--tile-size <integer (default: 256 256)>

Image tile size used for multi-threaded processing.


Tell GDAL to not create bigtiffs.

--tif-compress <None|LZW|Deflate|Packbits (default: LZW)>

TIFF compression method.

-v, --version

Display the version of software.

-h, --help

Display this help message.