SciPy Vector Alignment: Rotation, Weights, and Residual

SciPy vector alignment estimates a rotation from paired vector observations. Each pair describes the same item in two frames, and the returned rotation maps one set toward the other. The fit depends on how the pairs are ordered, their weights and the lengths of the vectors. The reported residual measures a remaining vector difference after alignment.

The returned rotation maps the second input toward the first

The SciPy 1.16.0 Rotation.align_vectors reference names the first set a and the second set b. The rotation acts on the vectors in b so that the rotated vectors come as close as possible to their partners in a. Rows are paired in their given order. If a record switches the order of the two frames, it changes which direction the returned transformation represents.

For example, imagine a direction that points upward on a sketch of the target frame but to the right on a sketch of the source frame. If the upward vector belongs in a and the rightward vector belongs in b, the returned rotation is applied to the rightward vector. The two frame labels matter even when both sets have the same array shape.

The input vectors already need to describe known correspondences. The function does not match one unordered group to another. It also estimates rotation alone. If the original measurements are points from different origins, their displacement or translation must be handled by a model appropriate to that data before interpreting the result as a comparison of directions.

Weights express how strongly pairs contribute

The documented loss adds the squared distance between each target vector and its rotated partner, multiplying each term by a weight. A larger weight increases the contribution of that pair to the objective for the same squared error. When the input weights are omitted, each explicit weight is one.

Vector lengths also affect the fit. For fixed lengths, the squared difference between two vectors includes a term depending on the cosine of their angular separation multiplied by the product of their lengths. A pair of long vectors can therefore exert more influence on the chosen rotation than a pair of short vectors. If the task treats each nonzero vector as a direction alone, normalizing to unit length changes that interpretation.

A nonzero residual can remain after exact directional alignment

The function reports rssd, the square root of the weighted sum of the remaining squared vector differences. A rotation preserves length. If a pair points in exactly the same direction after alignment but one vector is longer, there is still a nonzero difference between their tips.

For a hypothetical pair with weight one, take vectors of lengths two and three pointing along the same axis. The best direction match leaves their tips one unit apart, and that pair contributes a residual magnitude of one. If both vectors are normalized first, the residual for that pair can vanish. The two calculations answer different questions about the original inputs.

A single direction leaves a twist undetermined

The SciPy reference documents a special case for one vector pair. It returns the shortest rotation that aligns the direction in b with the direction in a. Once a direction has been matched, rotations about that common direction could keep it matched. The shortest-rotation choice supplies one answer where the measurement itself does not fully determine orientation.

The same reference treats a single infinite weight as a primary directional constraint and uses the remaining vectors to choose rotation about it. That special case also explains why the routine disallows the ordinary sensitivity output for a single pair or an infinite weight. The constraint changes the interpretation of the fit.

Keep the class of allowed transformations explicit

SciPy's orthogonal Procrustes reference describes a related matrix fit with a broader allowed class for real matrices. Its orthogonality constraint permits reflections as well as rotations. It also uses a row-matrix convention in which the source matrix is multiplied on the right. A reflection can preserve lengths and still reverse handedness, so an orthogonal fit and a proper spatial rotation are different requirements.

For real three-dimensional matrices, a proper rotation has determinant positive one. An orthogonal matrix with determinant negative one changes handedness. A smaller fitting residual from an orthogonal fit can therefore come from allowing a transformation that a rotation-only problem excludes. The Procrustes result named scale is a sum of singular values, and the documented orthogonal fit itself does not scale the inputs.

A learning record can identify the frame order, how rows correspond, whether vector lengths were retained and what transformations the chosen function allows. It can also preserve the residual's definition when comparing runs. Related explanations appear in the robot learning section and the technical article directory.