state_index_intrinsics.docstring

Return the index in the optimization vector of the intrinsics of camera i

SYNOPSIS

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

    optimization_inputs = m.optimization_inputs()

    b = mrcal.optimizer_callback(**optimization_inputs)[0]
    mrcal.unpack_state(b, **optimization_inputs)

    icam_intrinsics = 1
    i_state = mrcal.state_index_intrinsics(icam_intrinsics,
                                           **optimization_inputs)

    Nintrinsics = mrcal.lensmodel_num_params(optimization_inputs['lensmodel'])
    intrinsics_data = b[i_state:i_state+Nintrinsics]

The optimization algorithm sees its world described in one, big vector of state.
The optimizer doesn't know or care about the meaning of each element of this
vector, but for later analysis, it is useful to know what's what. The
mrcal.state_index_...() functions report where particular items end up in the
state vector.

THIS function reports the beginning of the i-th camera intrinsics in the state
vector. The intrinsics are stored contiguously. They consist of a 4-element
"intrinsics core" (focallength-x, focallength-y, centerpixel-x, centerpixel-y)
followed by a lensmodel-specific vector of "distortions". The number of
intrinsics elements (including the core) for a particular lens model can be
queried with mrcal.lensmodel_num_params(lensmodel). Note that
do_optimize_intrinsics_core and do_optimize_intrinsics_distortions can be used
to lock down one or both of those quantities, which would omit them from the
optimization vector.

In order to determine the variable 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

- lensmodel: string specifying the lensmodel we're using (this is always
  'LENSMODEL_...'). The full list of valid models is returned by
  mrcal.supported_lensmodels(). This is required if we're not passing in the
  optimization inputs

- do_optimize_intrinsics_core
  do_optimize_intrinsics_distortions
  do_optimize_extrinsics
  do_optimize_calobject_warp
  do_optimize_frames

  optional booleans; default to True. These specify what we're optimizing. See
  the documentation for mrcal.optimize() for details

- Ncameras_intrinsics
  Ncameras_extrinsics
  Nframes
  Npoints
  Npoints_fixed
  Nobservations_board

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

RETURNED VALUE

The integer reporting the location in the state vector where the contiguous
block of intrinsics for camera icam_intrinsics begins. If we're not optimizing
the intrinsics, or we're asking for an out-of-bounds camera, returns None