Provided by: mrcal_2.1-5build1_amd64 
NAME
mrcal-convert-lensmodel - Converts a camera model from one lens model to another
SYNOPSIS
$ mrcal-convert-lensmodel
--viz LENSMODEL_OPENCV4 left.cameramodel
> left.opencv4.cameramodel
... lots of output as the solve runs ...
RMS error of the solution: 3.40256580058 pixels.
... a plot pops up showing the differences ...
DESCRIPTION
Given a camera model, this tool computes another model that represents the same lens, but
using a different lens model. While lens models all exist to solve the same problem, the
different representations don't map to one another perfectly, and this tool seeks to find
the best-fitting parameters of the target lens model. Two different methods are
implemented:
1. If the given cameramodel file contains optimization_inputs, then we have all
the data that was used to compute this model in the first place, and we can
re-run the original optimization, using the new lens model. This is the
default behavior. If the input model doesn't have optimization_inputs, an
error will result, and the other method must be selected by passing --sampled
2. We can sample lots of points on the imager, unproject them to observation
vectors in the camera coordinate system, and then fit a new camera model that
reprojects these vectors as closely to the original pixel coordinates as
possible. Select this mode by passing --sampled.
The first method is preferred. Since camera models (lens parameters AND geometry) are
computed off real pixel observations, the confidence of the final projections varies
greatly, depending on the location of the points being projected. The first method uses
the original data, so it implicitly respects these uncertainties 100%: low-data areas in
the original model will also be low-data areas in the new model. The second method,
however, doesn't have this information: it doesn't know which parts of the imager are
reliable and which aren't, so the results won't be as good.
As always, the intrinsics have some baked-in geometry information. Both methods optimize
intrinsics AND extrinsics, and output cameramodels with updated versions of both. If
--sampled, then we can request that only the intrinsics be optimized by passing
--intrinsics-only. Also, if --sampled then we fit the extrinsics off 3D points, not just
observation directions. The distance from the camera to the fitting points is set by
--distance. Set this to the distance where you expect the intrinsics to have the most
accuracy. This is only needed if --sampled and not --intrinsics-only.
If --sampled, we need to consider that the model we're trying to fit may not fit the
original model in all parts of the imager. Usually this is a factor when converting wide-
angle cameramodels to use a leaner model: a decent fit will be possible at the center,
with more and more divergence as we move towards the edges. We handle this with the
--where and --radius options to allow the user to choose the area of the imager that is
used for the fit. This region is centered on the point given by --where (or at the center
of the imager, if omitted). The radius of this region is given by --radius. If '--radius
0' then I use ALL the data. A radius<0 can be used to set the size of the no-data margin
at the corners; in this case I'll use
r = sqrt(width^2 + height^2)/2. - abs(radius)
There's a balance to strike here. A larger radius means that we'll try to fit as well as
we can in a larger area. This might mean that we won't fit well anywhere, but we won't do
terribly anywhere, either. A smaller area means that we give up on the outer regions
entirely (resulting in very poor fits there), but we'll be able to fit much better in the
areas that remain. Generally empirical testing is required to find a good compromise: pass
--viz to see the resulting differences. Note that --radius and --where applies only if
we're optimizing sampled reprojections; if we're using the original optimization inputs,
the options are illegal.
OPTIONS
POSITIONAL ARGUMENTS
to The target lens model
model Input camera model. If "-' is given, we read standard
input
OPTIONAL ARGUMENTS
-h, --help show this help message and exit
--sampled Instead of solving the original calibration problem
using the new lens model, use sampled imager points.
This produces biased results, but can be used even if
the original optimization_inputs aren't available
--gridn GRIDN GRIDN Used if --sampled. How densely we should sample the
imager. By default we use a 30x20 grid
--distance DISTANCE Used (and required) if --sampled and not --intrinsics-
only. A sampled solve fits the intrinsics and
extrinsics to match up reprojections of a grid of
observed pixels. The points being projected are set a
particular distance (set by this argument) from the
camera. Set this to the distance that is expected to
be most confident for the given cameramodel. Points at
infinity aren't explicitly supported: specify a high
distance instead
--intrinsics-only Used if --sampled. By default I optimize the
intrinsics and extrinsics to find the closest
reprojection. If for whatever reason we know that the
camera coordinate system was already right, or we need
to keep the original extrinsics, pass --intrinsics-
only. The resulting extrinsics will be the same, but
the fit will not be as good. In many cases, optimizing
extrinsics is required to get a usable fit, so
--intrinsics-only may not be an option if accurate
results are required.
--where WHERE WHERE Used if --sampled. I use a subset of the imager to
compute the fit. The active region is a circle
centered on this point. If omitted, we will focus on
the center of the imager
--radius RADIUS Used if --sampled. I use a subset of the imager to
compute the fit. The active region is a circle with a
radius given by this parameter. If radius == 0, I'll
use the whole imager for the fit. If radius < 0, this
parameter specifies the width of the region at the
corners that I should ignore: I will use sqrt(width^2
+ height^2)/2. - abs(radius). This is valid ONLY if
we're focusing at the center of the imager. By default
I ignore a large-ish chunk area at the corners.
--viz Visualize the differences between the input and output
models
--num-trials NUM_TRIALS
If given, run the solve more than once. Useful in case
random initialization produces noticeably different
results. By default we run just one trial, which
hopefully should be enough
REPOSITORY
<https://www.github.com/dkogan/mrcal>
AUTHOR
Dima Kogan, "<dima@secretsauce.net>"
LICENSE AND COPYRIGHT
Copyright (c) 2017-2021 California Institute of Technology ("Caltech"). U.S. Government
sponsorship acknowledged. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License"); You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0