This issue contains the feedback from @mjrainbow and his team on the tutorials for Autoscoper.

From Mike's email:

Dajung

Loading and Tracking Data Tutorial Notes
Things to Note:

1. The tutorial doesn't provide any instructions on how to align both views,
which is particularly challenging for beginners like me.

2. It would be really helpful if I could get some tips and tricks 
from the team that I can learn and apply on my own. One great tip I 
received from Ali was to rotate the view so that two axes form a cross. 
This way, when I need to translate, I can easily use the two axis points for a smoother workflow.

3. It was quite hard for me to grasp the logical flow of 
working with the two views. I found myself going back and forth on the axes, 
trying to figure out how to get them aligned properly. But it would have been helpful 
for the tutorial to instruct me on that. 

4. Another issue I faced was that the axis lines were really tricky to click 
on. I often ended up misclicking and messing up the alignment, which was quite frustrating.

5. Towards the end of the tutorial, they briefly showed us how to view 
the model in worldview. However, they didn't explain what exactly we 
should be looking for or what it signifies.

Simon

I felt that the tutorial was straight forward. 

My advice: 
-the axes lines can be slightly larger to see for those with visual impairments. I would also misclick the rotation the rotation axes that I wanted to move and would accidentally shift the bone more than I wanted from the cyan colour rotation. 

-Within the tutorial, maybe explain how the axes relate to each other for the two frames. For example, when Dajung came to me to explain the UI, she showed me that I should make a cross with one side of the frame in rotation view, and then in translate view it was easier to work with with two axes on one frame and three on the other, and then I can play around going back and fourth from views. It just made it easier when rotating everything.

-I think it could be helpful to implement a "back" button if I made a mistake. I know that you can save, and then contrl + z, but for smaller changes it would be helpful to be able to go back relatively quicker, instead of clicking s every time. 

Ali

- The instructions describing how to move the volume were clear, but tips for the techniques of moving the volume to get it aligned would be useful (similar to those we have on the wiki)
- It wasn't clear that you need to go through and check each frame after optimizing to make sure each one is aligned
- Instructions on how to load in trials that have previously been worked on would also be useful as a point about general use of autoscoper. Although this training trial was short and it wasn't something I was stepping away from and coming back to, when I was doing the training for our lab I didn't realize you could come back into a trial you were tracking rather than having to do it all in one go

Updates to be made

Tutorial Updates

[x] Tips and tricks for aligning the ridged bodies with the radiographs
[x] How to use the world view to ensure the ridged bodies are aligned
[x] Saving data and resuming mid-workflow

Within the tutorial, maybe explain how the axes relate to each other for the two frames. For example, when Dajung came to me to explain the UI, she showed me that I should make a cross with one side of the frame in rotation view, and then in translate view it was easier to work with with two axes on one frame and three on the other, and then I can play around going back and fourth from views. It just made it easier when rotating everything.

[x] This is going to be dataset dependent, but for the sake of the tutorial, I can talk about the sample data we are using.
[x] Add warning to the tutorial homepage to ensure that users are familiar with the UI (and link to the UI page)
[x] Add a warning to the sample data tutorial that filters may need to be adjusted
[x] Add a note to let users know, that the alignment and tracking only pertains to the selected bone.
[x] Reference the tracking dialog UI page from the tutorials

Include disclaimer that this is not intended to be used with the sample data,

[x] This tutorial (loading custom data) can still be followed with the sample data (although it is generalized for any dataset), however, a brief section on how to find the sample data (slicer cache dir) would be a good idea
[x] Add warning about unsaved data in the config file tutorial
[x] Make a new shortcuts sections, that goes over all of the keyboard shortcuts

Autoscoper Updates

[x] Thicker axis lines (togglable, maybe colorblind and other modes) - via #141
[ ] More save states (ie. don't need to press s to go back to a prev pose with Ctrl+z) [Maybe two save states, Ctrl + Shift + Z goes back to the prev keyframe while Ctrl + Z goes back to the prev movement]

I never used the software prior to working through the tutorial (knee data), and discussed thoughts with @amymmorton afterward:

At the start:

Include disclaimer directing tutorial users who are unfamiliar with the UI, to go to the UI section of the documentation before working with the sample data

In the "Tracking a Skeletal Structure Section: Aligning a Volume"

Include a hint noting that to track the models, the user should manually align the models to the radiograph images for at least two frames, and then use the tracking dialog to track the frames in between. - Suggestion: This might be more intuitive with more than 3 frames to work with
Include a hint noting that each bone is individual. Using (s) to set keyframe sets the keyframe only for the selected bone, not all the bones that the user might have aligned with the image.
Include a link to the section on adjusting the contrast/filters. I needed this section when aligning the volumes, could be good to have a link to it when the user is going through the process. (Or include disclaimer that the sample filters may not be the most optimal for tracking, so see the "Rendering and Filters" section of the tutorial)

In "Tracking a Skeletal Structure Section: Tracking the volume"

Include a link to the Tracking Dialog section in the UI documentation for if the user would like a more detailed explanation of the options available (same as done in the "See also" section of the "Saving the tracking results"
Note, same as with setting keyframes, tracking is performed only on the selected bone, not all the bones aligned in the frame.

In the "Loading Custom Data"

Include disclaimer that this is not intended to be used with the sample data, but this is how the user would load in data of their own (following the last section, it was not intuitive that this is not something the user can practice/test with the sample data)

In the "Creating a Configuration File"

Include disclaimer noting that if you currently have files open (that have not been saved), you will be prompted to save them prior to seeing the dialog box shown in the tutorial. new_config_file.pdf

Another note: when you click control + v (or paste), while a model is selected, it will move the model to the way it was oriented/located on the most recently saved keyframe (by clicking "s"). If the user has not already set a keyframe, it will move the model to its original starting position (for example, the tibia will go back to the corner of the radiograph)

BrownBiomechanics / Autoscoper

July 2023: Tutorial Feedback from Skeletal Observation Laboratory at Queen's University #140

Updates to be made

Tutorial Updates

Autoscoper Updates