Merge pull request #102 from AnyBody/update_scaling_tutorials

Update scaling lesson

Author: melund

Scaling/_static/lesson4/image1.png

@@ -3,9 +3,9 @@
 This lesson explains how we can use our own custom scaling function,
 which we designed in Lesson 3 and combine it with the overall human body scaling laws.
 
-:::{seealso}
+```{seealso}
 The section on scaling in the AMMR documentation.
-:::
+```
 
 ## Preparing for subject-specific scaling
 
@@ -22,21 +22,15 @@ from a CT-scan of one of his left femur. To increase the accuracy of our model,
 let us improve it using a subject-specific scaling for the femur.
 
 First of all, let us prepare a model matching the standard size man to
-be the basis for further subject-specific improvements. Therefore we use the model from the
-first section **ScalingStandard,** StandingModelScalingDisplay from the
-AnyBody Managed Model Repository (AMMR). This is well suited to show how
+be the basis for further subject-specific improvements. Therefore we use the [StandingModelScalingDisplay](ammr:sphx_glr_auto_examples_other_plot_standingmodelscalingdisplay.py) from the AnyBody Managed Model Repository (AMMR), with the `_SCALING_STANDARD_`, option. This is well suited to show how
 to use subject-specific geometry in a model.
 
 ## Including custom scaling for a single segment
 
 Let us configure this example to use ScalingStandard. We need to define
 `BM_SCALING` as `_SCALING_STANDARD_` and out-comment all other parts of
 the scaling configuration block. With this setting, the model is now scaled to
-the generic size. We can now include individual scaling functions for each segment,
-which will be done in a special file *CustomScaling.any*, where all the
-modifications related to individual segment morphing are recommended to be done.
-This file is already present in the example and you can include it as shown
-below:
+the generic size. 
 
 ```AnyScriptDoc
 /*------------- SCALING CONFIGURATION SECTION --------------------*/
@@ -47,32 +41,29 @@ below:
 //  #define BM_SCALING _SCALING_UNIFORM_
 //  #define BM_SCALING _SCALING_LENGTHMASS_
 //  #define BM_SCALING _SCALING_LENGTHMASS_FAT_
+```
 
 
-// Scaling laws using external measures
-//  #define BM_SCALING _SCALING_UNIFORM_EXTMEASUREMENTS_
-//  #define BM_SCALING _SCALING_LENGTHMASS_EXTMEASUREMENTS_
-//  #define BM_SCALING _SCALING_LENGTHMASS_FAT_EXTMEASUREMENTS_
+We can now include individual scaling functions for each segment,
+which will be done in a special file {file}`CustomScaling.any`, where all the
+modifications related to individual segment should be be done.
+This file is already present in the example and you can include it as shown
+below:
 
-// Anthropometric data file (unchanged files can be found in AAUHuman\Scaling\AnyFamily)
-//  #path BM_SCALING_ANTHRO_FILE "Model\AnyFamily\AnyMan.any"
-//  #path BM_SCALING_ANTHRO_FILE "Model\AnyFamily\AnyManUniform.any"
-//  #path BM_SCALING_ANTHRO_FILE "Model\AnyFamily\AnyManExternal.any"
-//  #path BM_SCALING_ANTHRO_FILE
-"Model\AnyFamily\AnyManExtPercentile.any"
-//  #path BM_SCALING_ANTHRO_FILE
-"Model\AnyFamily\AnyWomanExtPercentile.any"
+```AnyScriptDoc
 //--------------- END OF SCALING CONFIGURATION -------------------
 
 §#include "Model\CustomScaling.any"§
 
 #include "<ANYBODY_PATH_BODY>/HumanModel.any"
 ```
 
-In case you want to personalize your own model - just copy CustomScaling.any
+:::{tip}
+In case you want to personalize your own model - just copy {file}`CustomScaling.any` 
 file into the Model folder and follow the instructions from this tutorial.
+:::
 
-If we open this file by a double click, we can see that a common place
+If we open this file (by a double click it), we can see that a common place
 to make modifications has already been prepared. Further, we can find
 an access point to the geometrical scaling law folder, which will be
 used to specify individual scaling laws.
@@ -90,13 +81,17 @@ transforms from the previous lesson. We also need to download the
 {download}`source <Downloads/SourceFemur.stl>` (native to AMMR) and
 {download}`target <Downloads/TargetFemur.stl>` (courtesy of Prof.
 Sebastian Dendorfer, OTH Regensburg, Germany) femur surface
-geometries, and copy them to the *Model* folder of the
-StandingModelScalingDisplay example. Now, we need to make several
+geometries. 
+
+Next copy these three files into the {file}`Model` subfolder in  the 
+*StandingModelScalingDisplay* example.
+
+Now, we need to make several
 small adjustments to the scaling law for smooth incorporation into the
 model structure.
 
-Starting from the AMMR v1.6.2, individual segment scaling function is
-implemented in the anatomical reference frame. We will call this frame
+In the **A**nyBody **M**anaged **M**odel **R**epository (AMMR) scaling functions are
+implemented in the anatomical reference frames. We will call this frame
 a scaling reference frame, since there might be several definitions of
 anatomical reference frames. In general, the segmental frame can be
 different from the scaling reference frame. The human body model
@@ -112,43 +107,37 @@ In our scaling law (MyScalingFunction.any) the source entities are
 
 - MyScalingFunction.AffineTransform.Points0,
 - MyScalingFunction.RBFTransform.Points0,
-- MyScalingFunction.STLTransform.Input.SourceSrf.
+- MyScalingFunction.STLTransform.Input.SourceSurf.
 
-In the AMMR version 1.6.2 such transformations will be segment dependent and
-will only be needed for right and left shank and femur as well as for
+In the **AMMR** such transformations will be segment dependent.  It is only be needed for right and left shank and femur as well as for
 the pelvis. For all other segments this transform can be defined as an
 identity transformation or does not have to be applied to the source
-entities. The following transforms can be referenced as TSeg2ScaleFrame,
-the name that will be used further:
+entities. The following transforms can be referenced as `TSeg2ScaleFrame` (**T**ransform **Seg**mental **2** to **Scale**ling **Frame**). That name that will be used further:
 
-- HumanModel.BodyModel.Left\[*Right*\].Seg.Thigh\[*Shank*\].Scale.T0
-- HumanModel.BodyModel.Trunk.SegmentsLumbar.PelvisSeg.Scale_Trunk_Pelvis.ScaleAfterInterfaceMorphingDef.Scale.T0.
+- `HumanModel.BodyModel.[Left/Right].Seg.[Thigh/Shank].Scale.T0`
+- `HumanModel.BodyModel.Trunk.SegmentsLumbar.PelvisSeg.Scale_Trunk_Pelvis.ScaleAfterInterfaceMorphingDef.Scale.T0`
 
-Starting from the AMMR v1.6.3 (corresponds to the AMS v 6.0.3) this
-transform, TSeg2ScaleFrame, is already defined and can be found in the
-subfolder of HumanModel.Scaling.GeometricalScaling, which corresponds to
+In the model repository this transform, `TSeg2ScaleFrame`, is already defined and can be found in the
+subfolder of `HumanModel.Scaling.GeometricalScaling`, which corresponds to
 the morphed segment and has a similar name. This transform can be easily
 accessed as demonstrated below and no extra actions are needed.
 
 Let us subject the source entities of the scaling law to the rigid body
-transformation, TSeg2ScaleFrame. We will need to make the following 3
-changes. Please note how we look up out of the *MyScalingFunction* folder
-using double and quadruple dots:
+transformation, `TSeg2ScaleFrame`. We will need to make the following 3
+changes. Please note how we look up out of the `MyScalingFunction` folder
+using `..` and `...` prefixes to the variables.:
+
+```{code-block} AnyScriptDoc
 
-```AnyScriptDoc
   AnyFunTransform3DLin2 AffineTransform =
   {
     Points0 = §..TSeg2ScaleFrame(§
     {{0.0138187,0.00136731,0.0273618},    // fovea capitis
-    ...
+-->8--
       {0.0368766,-0.393677,0.0266919}}§)§;    // medial posterior condyle
     Points1 =
     {{0.289913,0.420538,0.0138931},    // fovea capitis
-    ...
-      {0.261891,0.47585,-0.372696}};    // medial posterior condyle
-    Mode = VTK_LANDMARK_AFFINE;
-  };
-...
+-->8--
   AnyFunTransform3DRBF RBFTransform =
   {
     PreTransforms = {&.AffineTransform};
@@ -159,10 +148,10 @@ using double and quadruple dots:
     };
     Points0 = §..TSeg2ScaleFrame(§{
       { 0.0138, 0.0014, 0.0274},
-    ...
+-->8--
       { 0.0010, 0.0013, 0.0069}
     }§)§;
-...
+-->8--
   AnyFunTransform3DSTL STLTransform =
   {
     PreTransforms = {&.RBFTransform};
@@ -176,15 +165,15 @@ using double and quadruple dots:
 ```
 
 As you will see from the following changes the modification simply links
-the transformations to the folder containing our MyScalingFunction.any file.
+the transformations to the folder containing our `MyScalingFunction.any` file.
 In our case, this folder is
-HumanModel.Scaling.GeometricalScaling.Left.Thigh, which corresponds to
+`HumanModel.Scaling.GeometricalScaling.Left.Thigh`, which corresponds to
 the name of the segment, we are trying to morph, and contains our
-TSeg2ScaleFrame rigid body transform.
+`TSeg2ScaleFrame` rigid body transform.
 
 So finally let us add this scaling function to the model. Please
 insert the following lines as shown below into the file
-CustomScaling.any:
+{file}`CustomScaling.any`:
 
 ```AnyScriptDoc
 HumanModel.Scaling.GeometricalScaling = {
@@ -196,29 +185,28 @@ Left.Thigh = {
 };
 ```
 
-In this modification, we added a pre-processor command (#define) that
-notifies the model assembling block that the anthropometric scaling
-for the left thigh segment is not being used. To process other body
+In this modification, we added a pre-processor command (`#define`) that
+notifies the model assembling block that the default anthropometric scaling
+for the left thigh segment should be excluded. To process other body
 parts you will need to add a similar definition, but utilize actual
 bone segment, e.g. `#define CUSTOM_SCALING_<Side>_<SegmentName>` for
 different sides or `CUSTOM_SCALING_<SegmentName>` for parts of the
 body that do not have sides. You can find a list of segments by
 browsing the scaling law in the Model tab:
 
-```{image} _static/lesson4/image1.png
-:width: 50%
-```
+<img src="_static/lesson4/image1.png" alt="Scaling options in model tree">
+
 
 The other change was to assign the new custom scaling function to be
 used in the segment of the left thigh instead of the excluded one. If
-we now comment in DrawExternalMeasures.any and look in the Model View,
+we look in the Model View,
 we can see that the left femur is now shorter and a little thinner
 than with the standard scaling. So we have now successfully introduced
 our custom scaling law into the model.
 
-```{image} _static/lesson4/image2.png
-:width: 60%
-```
+
+<img src="_static/lesson4/image2.png" alt="Scaling options in model tree" width="60%">
+
 
 If we worked with a bone that does not have a controlateral pair, e.g.
 vertebrae, skull, etc., or just wanted to personalize a single side, we would
@@ -248,20 +236,20 @@ AnyFolder MyScalingFunction§_Mirrored§ = {
     {0,1,0},
     {0,0,-1}
   };§
-...
+-->8--
   AnyFunTransform3DLin2 AffineTransform =
   {
     Points0 = ..TSeg2ScaleFrame({...} §* .AMirroring§);
     Points1 = {...} §* .AMirroring§;
     Mode = VTK_LANDMARK_AFFINE;
   };
-...
+-->8--
   AnyFunTransform3DRBF RBFTransform =
   {
-    ...
+    -->8--
     Points0 = ..TSeg2ScaleFrame({...} §* .AMirroring§);
     Points1 = {...} §* .AMirroring§;
-    ...
+    -->8--
   };
 };  // MyScalingFunction§_Mirrored§
 ```