corresponding_icam_extrinsics.docstring

Return the icam_extrinsics corresponding to a given icam_intrinsics

SYNOPSIS

    m = mrcal.cameramodel('xxx.cameramodel')

    optimization_inputs = m.optimization_inputs()

    icam_intrinsics = m.icam_intrinsics()

    icam_extrinsics = \
        mrcal.corresponding_icam_extrinsics(icam_intrinsics,
                                            **optimization_inputs)

    if icam_extrinsics >= 0:
        extrinsics_rt_fromref_at_calibration_time = \
            optimization_inputs['extrinsics_rt_fromref'][icam_extrinsics]
    else:
        extrinsics_rt_fromref_at_calibration_time = \
            mrcal.identity_rt()

When calibrating cameras, each observation is associated with some camera
intrinsics (lens parameters) and some camera extrinsics (geometry). Those two
chunks of data live in different parts of the optimization vector, and are
indexed independently. If we have STATIONARY cameras, then each set of camera
intrinsics is associated with exactly one set of camera extrinsics, and we can
use THIS function to query this correspondence. If we have moving cameras, then
a single physical camera would have one set of intrinsics but many different
extrinsics, and this function will throw an exception.

Furthermore, it is possible that a camera's pose is used to define the reference
coordinate system of the optimization. In this case this camera has no explicit
extrinsics (they are an identity transfomration, by definition), and we return
-1, successfully.

In order to determine the camera mapping, we need quite a bit of context. If we
have the full set of inputs to the optimization function, we can pass in those
(as shown in the example above). Or we can pass the individual arguments that
are needed (see ARGUMENTS section for the full list). If the optimization inputs
and explicitly-given arguments conflict about the size of some array, the
explicit arguments take precedence. If any array size is not specified, it is
assumed to be 0. Thus most arguments are optional.

ARGUMENTS

- icam_intrinsics: an integer indicating which camera we're asking about

- **kwargs: if the optimization inputs are available, they can be passed-in as
  kwargs. These inputs contain everything this function needs to operate. If we
  don't have these, then the rest of the variables will need to be given

- Ncameras_intrinsics
  Ncameras_extrinsics
- Nobservations_board
- Nobservations_point
  optional integers; default to 0. These specify the sizes of various arrays in
  the optimization. See the documentation for mrcal.optimize() for details

- indices_frame_camintrinsics_camextrinsics: array of dims (Nobservations_board,
  3). For each observation these are an
  (iframe,icam_intrinsics,icam_extrinsics) tuple. icam_extrinsics == -1
  means this observation came from a camera in the reference coordinate system.
  iframe indexes the "frames_rt_toref" array, icam_intrinsics indexes the
  "intrinsics_data" array, icam_extrinsics indexes the "extrinsics_rt_fromref"
  array

  All of the indices are guaranteed to be monotonic. This array contains 32-bit
  integers.


RETURNED VALUE

The integer reporting the index of the camera extrinsics in the optimization
vector. If this camera is at the reference of the coordinate system, return -1