Enhance Scaling Tutorial: Add detailed explanations for model personalization and scaling functions

Author: Jacob Hilmar Adamsen

Scaling/_static/lesson2/image4.png

@@ -16,6 +16,16 @@ instructions on how to configure the model to use the built-in *scaling laws*
 and provide general anthropometric information.
 :::
 
+Scaling schemes described in the AMMR documentation are based on
+anthropometric measurements and affine transform scaling. Such schemes
+are good assumptions when more accurate measurements are not feasible or not
+available. Therefore, these schemes are used quite often. However, a
+natural next step would be to improve the precision of a model by
+utilizing subject-specific geometry available from the medical images. Medical images
+contain more subject-specific information about the bone shapes and local
+deformities that cannot be handled by the anthropometric regression
+equations.
+
 This tutorial introduces an advanced procedure of model personalization by means of
 nonlinear morphing for both, bone surface and relevant soft tissue attachment sites,
 to take a subject-specific shape. In this example, bone geometries segmented from medical
@@ -32,6 +42,6 @@ with the basic scaling laws and concepts presented in the
 ```{toctree}
 :maxdepth: 1
 
-Lesson 1: Scaling based on medical images <lesson1>
-Lesson 2: Including a custom scaling function into your model <lesson2>
+Lesson 1: Scaling Based on Medical Images <lesson1>
+Lesson 2: Including a Custom Scaling Function into Your Model <lesson2>
 ```

Scaling/index.md

@@ -3,29 +3,39 @@
 
 # Lesson 1: Personalizing Individual Segments Based on Geometric Data from Medical Images
 
+:::{note}
 This tutorial presumes that you have read the [AMMR documentation](https://anyscript.org/ammr/Scaling/intro.html)
 and know how to personalize your model using information about height, weight,
 and individual segment lengths.
+:::
+
+In this lesson you will learn how to personalize a bone segment (the femur) so
+a generic model matches a specific person’s anatomy from medical imaging. We do
+this by scaling the bone surface, starting with basic affine
+transformations and advancing to more sophisticated nonlinear methods.
 
-This lesson introduces an advanced approach to scaling based on a sequence of
+You will be introduced to an advanced approach to scaling based on a sequence of
 affine and non-affine transformations. Each of these transforms is constructed
 based either on subject-specific geometry or on a set of landmarks selected on
 the bone surface. As opposed to the simple scaling laws explained in the AMMR
 documentation, this lesson is rather methodological than conceptual and provides
 a good overview of how to pipeline and combine different 3D transforms to obtain
 subject-specific morphing and registration between frames of reference.
 
-## Linear Point-Based Scaling
+Shortly explained, the sections in this lesson are as follows:
+
+- **Linear Point-Based Scaling**: Using a *set of matching landmarks (points)* on
+  the source and target geometries to construct a *linear* transform
+  (move, rotate, scale, and skew) that scales the source into the target
+  geometry.
 
-Scaling schemes described in the AMMR documentation are based on
-anthropometric measurements and affine transform scaling. Such schemes
-are good assumptions when more accurate measurements are not feasible or not
-available. Therefore, these schemes are used quite often. However, a
-natural next step would be to improve the precision of a model by
-utilizing subject-specific geometry available from the medical images. Medical images
-contain more subject-specific information about the bone shapes and local
-deformities that cannot be handled by the anthropometric regression
-equations.
+- **Landmark-Based Nonlinearities**: Refining the scaling by adding a *nonlinear*
+  transform fitted to a *new set of matching landmarks (points)*.
+
+- **Surface-Based Nonlinearities**: Further refining the scaling by adding a
+  *nonlinear* transform fitted to the *surfaces* of the source and target geometries.
+
+## Linear Point-Based Scaling
 
 The simplest inclusion of the subject-specific bone shape from medical
 image data is to find the affine (linear) transformation that fits a
@@ -101,6 +111,20 @@ step, we change the mode of the `AnyFunTransform3DLin2` object to
 :end-before: //# END SNIPPET 1
 ```
 
+:::{admonition} Tip for landmark selection
+:class: tip dropdown 
+If you want to extract the coordinates of the points on the surfaces in *your own
+model*, you can use the open source software MeshLab, which can be downloaded
+{download}`here<https://www.meshlab.net/>`.
+
+1. Import the STL surface into MeshLab
+2. Use the `PickPoints` tool to select points on the surface by right-clicking
+   on the desired locations ![PickPoints](_static/lesson2/image4.png)
+3. Save the points to a file
+4. Open the saved file in a text editor and copy the coordinates of the points
+   into your AnyScript model (be aware of the order of the x-, y-, and z-coordinates)
+:::
+
 The selected points on the surface represent specific anatomical
 landmarks and points described in the comments of the AnyScript code.
 Final modification before we can use the constructed linear transform is

Scaling/lesson1.md

@@ -3,8 +3,20 @@
 
 # Lesson 2: Including a Custom Scaling Function into Your Model
 
-This lesson explains how we can use our own custom scaling function,
-which we designed in Lesson 1 and combine it with the overall human body scaling laws.
+This lesson explains how to use your own custom scaling function designed in
+Lesson 1 and combine it with the overall human body scaling laws, so
+anthropometric scaling and subject-specific scaling are combined.
+
+Shortly explained, the sections in this lesson are as follows:
+
+- **Prepare the base model**: Opening the Standing Human Model and preparing the
+  model for subject-specific scaling.
+
+- **Include your custom scaling function**: Add your custom scaling function
+  to personalize a single segment (the femur).
+
+- **Include a mirrored custom scaling function**: Apply the same custom scaling
+  to the opposite femur by mirroring the original scaling function.
 
 ```{seealso}
 This lesson uses the human body scaling laws presented in the AMMR, thus
@@ -210,16 +222,24 @@ scaling law into the model.
 :width: 50%
 ```
 
-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
-continue with running the inverse dynamics. But as an exercise, we want to
-continue and scale the other side as well to ensure symmetry of the model.
-Normally, we would use the contralateral patient-specific bone and
-copy the scaling code. But, in our case, only one side was available. We will assume
-that the body is symmetric, which is only true up to a certain extent.
-So let us include a similar scaling for the corresponding mirrored pair.
-In the next section we will describe how to introduce mirroring to our
-scaling functions.
+:::{warning}
+It is important to note that the scaling function so far only personalizes a
+single bone (one femur). The rest of the body still uses the standard body 
+model with anthropometric scaling laws.
+:::
+
+If we worked with a bone that does not have a contralateral pair (e.g. vertebrae
+or skull), or if you intentionally personalize only one side of the human body,
+we would continue with running the inverse dynamics. However, for paired
+segments like the femur it is recommended to also scale the other side of the
+model to ensure symmetry of the body. 
+
+Best practice is to have patient-specific geometry for both sides and reuse the
+scaling code with the second dataset. But, in this tutorial, only one side is
+available, so we assume that the body is symmetric, which is only true up to a
+certain extent. So let us include a similar scaling for the corresponding
+mirrored pair. In the next section we will describe how to introduce mirroring
+to our scaling functions.
 
 ## Introducing a Mirrored Custom Scaling Function