_Model Mass Scaling

Original issue https://github.com/opensim-org/opensim-core/issues/223

Gihub issue https://github.com/opensim-org/opensim-core/issues/231

Issue came about because of an email from Kat Steele in late 2014. The ScaleTool has two inputs for mass scaling— the mass input text box (MI) and the Preserve Mass Distribution checkbox (PRD).  The instructions were relatively clear on the ScaleTool documentation page;

"When the box for Preserve mass distribution during scale is checked, the total mass of the generic model is scaled so that it equals the mass of the subject while preserving the relative masses of its body segments. So, for example, if in the generic model the mass of the thigh is twice that of the shank, the mass of the thigh in the scaled model will also be twice that of the scaled shank. If this check box is not checked, the segment masses are scaled based solely on the scale factors applied to each body segment, and the total mass of the model will not equal the experimentally-measured mass of the subject."

However, Kat felt that even if you had PMD checked, if you had specified an input mass, the output mass of the model should be the same as the input mass. This was not happening in 3.3— if PMD was not checked, the input mass was ignored and the total mass of the scaled model would be the sum of the individual mass multipled by their own scale factors. 

Four options

Input mass is defined, preserve mass distribution is checked

The simplest case. Each body has its mass multiplied by the ratio of the target mass divided by the current mass. 

Input mass is defined, preserve mass distribution is unchecked

Two stages. First, new body masses are scaled by multiplying the body mass by the product of its scale factors— the new body masses are summed to give an intermediate total mass. Then the newly scaled body masses are scaled again by the ratio of the target mass divided by the intermediate mass. This insures that there is relative scaling between bodies while still respecting the target mass. 

Input mass is not defined, preserve mass distribution is checked

Input mass is not defined, preserve mass distribution is unchecked

Scaling code on Body https://github.com/opensim-org/opensim-core/blob/f3d78dec3ca08b38dc001791743d7cce78777807/OpenSim/Simulation/SimbodyEngine/Body.cpp#L205-#L215

Scaling code on Model https://github.com/opensim-org/opensim-core/blob/master/OpenSim/Simulation/Model/Model.cpp#L1420-#L1461