-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathunpack_state.docstring
72 lines (52 loc) · 2.81 KB
/
unpack_state.docstring
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
Scales a state vector from the packed, unitless form used by the optimizer
SYNOPSIS
m = mrcal.cameramodel('xxx.cameramodel')
optimization_inputs = m.optimization_inputs()
b_packed = mrcal.optimizer_callback(**optimization_inputs)[0]
b = b_packed.copy()
mrcal.unpack_state(b, **optimization_inputs)
In order to make the optimization well-behaved, we scale all the variables in
the state and the gradients before passing them to the optimizer. The internal
optimization library thus works only with unitless (or "packed") data.
This function takes a packed numpy array of shape (...., Nstate), and scales it
to produce full data with real units. This function applies the scaling directly
to the input array; the input is modified, and nothing is returned.
To unpack a state vector, you naturally call unpack_state(). To unpack a
jacobian matrix, you would call pack_state() because in a jacobian, the state is
in the denominator.
Broadcasting is supported: any leading dimensions will be processed correctly,
as long as the given array has shape (..., Nstate).
In order to know what the scale factors should be, and how they should map to
each variable in the state vector, 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
- b: a numpy array of shape (..., Nstate). This is the packed state on input,
and the full state on output. The input array is modified.
- **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
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
None. The scaling is applied to the input array