digitMesh.mesh3d: Digitizes a Mesh
In morphOptics/digit3DLand: Digitalization of 3D landmarks on mesh

Description Usage Arguments Details Value See Also

Interactive digitization of a mesh3d object.

1
2
3

## S3 method for class 'mesh3d'
digitMesh(specFull, specDecim, fixed, idxFixed = 1:fixed, templateCoord = NULL,
          idxTemplate = NULL, GrOpt = setGraphicOptions(), verbose = TRUE)

`specFull`	Full resolution mesh3d object.
`specDecim`	Decimated resolution mesh3d object, as obtained through `decimMesh.mesh3d` for example. If missing, the mesh will be decimated to the `tarface` target value.
`fixed`	Number of landmarks to digitize.
`idxFixed`	Numeric vector with `fixed` positive integers specifing the landmark ordering in which the landmarks will be digitized. Default: `1:fixed`, meaning that landmarks will be digitized following the ordering of their numbers.
`templateCoord`	Numeric matrix with three columns (x,y,z) and at least four lines indicating the coordinates of at least four 3D points needed to fit the template configuration on the mesh. Warning: The landmarks in the template configurations should be sorted following their numbers, even if the landmarks used to fit it on the mesh aren't stored in the first lines of this matrix. In such a case, it should be specified with `idxTemplate`. Default: `NULL` => no template will be used.
`idxTemplate`	Numeric vector with positive integers indicating the numbers of landmarks of the template used to fit it on the mesh, sorted in the order with which they will be digitized on the mesh. For example, if the landmarks used are the landmarks numbered 10, 12, 17 and 23, and digitized in the following order on the mesh: 12, 10, 23, 17, `idxTemplate` should be set to: `c(12, 10, 23, 17)`. Default: `NULL` => no template will be used, but corrected to `1:4` if `templateCoord` is provided, but not `idxTemplate`.
`GrOpt`	List defining options for graphic rendering. See `setGraphicOptions` for details.
`verbose`	Possible settings are: - a logical value: in this case this value should be recycled in a 2 length vector indicating for 2 levels of verbose if comments should be printed or not on screen as the computations are processed. The firs level corresponds to comments specific to the functions from the `digit3DLand` library, and the second one to comments specific to the functions from the `Rvcg` library. - a 2-length logical vector standing for the 2 possible levels of verbose.
`tarface`	Number of target faces to decimated the mesh, used if specDecim is missing.
`spec.name`	Attribute for the returned A array indicating the specimen name. Possible settings are: - NULL (default): array name is set as the mesh3d object name - a character value given the array name.

This function allows to interactively digitize p=fixed landmarks on the surface of a mesh, using two versions of this mesh:
- a decimated version (specDecim) to grossly positionned in a first time a given landmark,
- and then the full resolution version of the mesh (specFull) to finely positionned this landmark on a zoomed area around the previously positionned landmark
User should interact first on the decimated mesh, and then, landmark location will be validated on the full resoltution mesh.

The rationale to adopt a two steps approach to position landmarks through the use of a decimated mesh was motivated by several causes:
1/ The user interactions with the mesh (as the rotation, the zoom, and also the landmark location) can become time-consuming for heavy meshes, making not fluid at all the mesh digitizing.
2/ The automatic display of the zoomed zone allowed to question user on its landmark positionning if it has been made with a low magnfication.
3/ Because mesh translation is not possible with this function, the zoomed zone allows to digitize more easily landmarks distant from the mesh (and rotation) center.

a. Basic process for landmark digitization

Mouse and keyboard interactions for landmark digitization:
- left click: mesh rotation
- scroll wheel: zoom and dezoom
- right click for Windows users, and cmd + right click for Mac users: digitize a landmark
- Escap key press: validate the landmark positionning (and then pass to the next landmark digitizing)

In its basic version, the function process divides into 2 steps:
1/ Landmark digitizing
2/ Once all the landmarks are digitized, user can modify (or not) any of them as many time as wanted.

During step 1/, user should first grossly position a landmark on the decimated mesh (step 1a/). While the landmark is not validated by the Escape key, the user is free to re-position as many time as wanted the landmark (rotation and zoom can be changed as well). Once the Escape key is pressed, the zoomed full resolution mesh appears (step 1b/), to finely positioned the landmark. As before, the user can change the landmark positioning, and will definitely validate it by the Escape key to digitize then the next landmark.

Once all the landmarks are positionned, the step 2/ allow user to modify (if necessary) any landmark. Just click on (or near) the landmark to modify and then, the process is the same as the one described for step 1/ (1a/ & 1b/). Once the user estimates that all landmarks are correctly positionned, The digitization of the mesh is validated by closing the graphic device (red cross). If no landmark needs modification, the device can be closed as soon as the step 1/ is done.

WARNING: be carreful that the window should be closed once all landmark are validated, meaning that step 1b/ should be finished, and that no one landmark modification during step 2/ is in progress. To ensure of this, the zoomed mesh shouldn't be visible anymore, and all landmarks on the decimated mesh should have the same color (blue by default). Otherwise, the landmark coordinates won't be exported.

b. First refinement: using a template configuration

A configuration matrix of landmark coordinates (templateCoord) can be used as a template to fasten the digitization process. In this case, user should first digitize few landmarks (set with idxTemplate) on the treated mesh, and once they are positionned, the function computes first rigid transformations (translation, scaling, rotation) to fit the template first landmarks onto the first digitized landmarks from the digitized mesh, then apply those transformations on the full template configuration, and finally project the template landmark onto the digitzed mesh.

Those projected landmarks from template on the mesh are expected (at least for small shape variablity cases, and with a judicious choice for the template configuration) to be positionned near the actual landmark to digitize. Consequently, the function uses this information of approximative position for the remainging landmarks as an assesment of the zone where the final landmarks should be positionned. Concretely, during the digitization process, the template projection of remaining landmark allows to automatically process the step 1a/ without need of user interaction, and the zoomed full mesh is automatically assessed for each landmark, and user needs only to finely position them on during step 1b/.

Note 1: It can occur that the assessed zoomed mesh doesn't correspond to the actual zone where the landmark should be positioned. If so, and because step 1b/ will process automatically each landmark the ones after the others, you can simply incorrectly positioned this landmark, and modify it later during step 2/.

Note 2: The first few digitized landmarks used to fit the template on the mesh are decisive to obtain a good positioning of the remainging landmarks. We advise user to choose at least 4 landmarks, sufficiently spaced each one with other and describing the whole mesh in its 3 dimensions (so avoiding to choose landmarks positionned in a single plane).

Note 3: In its current version, the function doesn't allow to modify these first landmarks before to fit the tempalte. So, if some of those landmarks are uncorrectly positionned, it can highly impact the projection of the remaining landmarks and then the assessment of the zoomed zones. Thus, we can only encourage user to be carreful on the positioning of those landmarks to avoid to have to modifiy most of the landmarks during the step 2/...

c. Second refinement: using mesh/plane intersection as a guideline to digitize landmark

An optional preliminary step allow user to interactively rotate plane(s) intersecting the mesh, and to keep a record of this intersection during the landmark digitizing. It could be of interest when some landmarks to digitize are located along a symmetry axis. To process this step, user should set options of the GrOpt argument (through the function setGraphicOptions, see associated help for details).

Mouse and keyboard interactions for plane rotation:
- left click: mesh & plane(s) rotation as a single block
- scroll wheel: zoom and dezoom
- right click for Windows users, and cmd + right click for Mac users: rotation of the mesh while the plane(s) stay fixed.
- Escap key press: validate the plane(s) positioning (and then pass to the landmark digitization)

With this option, the function process divides into 3 steps:
0/ Plane(s) rotation
1/ Landmark digitizing
2/ Once all the landmarks are digitized, user can modify (or not) any of them as many times as necessary.

During step 0/, user is free to rotate as many time as wanted the plane(s) relative to the mesh. The rotation is validated by pressing the Escap key. Then , steps 1/ and 2/ will be processed as described before. Note that the proposed planes are limited to the planes made by major axes of the mesh, so that from 1 to 3 planes can be drawn, they are orthogonal each one to the other, and they are centred on the mesh centroid.

A numeric matrix with fixed lines and 3 columns containing the 3D coordinates of the digitized landmarks.

digitMesh.character.

morphOptics/digit3DLand documentation built on July 17, 2021, 8:27 p.m.