cornelmpop / lithics3d

An R package for processing and analyzing 3D scans of archaeological lithics

Lithics3D

Lithics3D provides a toolbox for working with 3D scans of archaeological lithics (and other objects) within the R environment. The functions included herein are designed to work with clean triangular meshes. For the time being at least, mesh generation and pre-processing (e.g. cleaning) must be done with different tools (e.g. Meshlab).

The included functions can be divided into three broad categories:

• High-level functions for (semi-)automatic segmentation and analysis of meshes qua archaeological artifacts (e.g. utilities for automatically measuring edge angles, mapping artifact thickness).

• Low-level functions for working with meshes as geometric objects. These functions are meant to provide the building blocks required to implement more complex functionality.

• Interactive functions for visual mesh processing (e.g., selecting points and paths of interest on the object's surface).

Warning: A note on current status

This package incorporates functions written over a period of several years. Some of these functions are far more experimental than others, and there are many naming inconsistencies which are slowly being resolved. You can expect function names to change without notice, but all functions added in or since the v0.4.0 release will continue working as originally documented until version 1 of the package.

Given the experimental nature of some of the functions included in this package you are strongly encouraged to double check your results and contact me for help or clarification, or better yet, open an issue (see Lithics3D Issues)! More generally, be mindful of the fact that this is very much a work in progress.

Getting started

Installation

If you haven't done so already, install devtools in R:

install.packages("devtools")

Once devtools is available you can install Lithics3D from github with the following R commands:

require(devtools)
install_github("cornelmpop/Lithics3D", dependencies=T, build_vignettes=T)

Using Lithics3D

For basic information about the package, including a list of available functions and data, please load the package and consult the manual:

library(Lithics3D)
?Lithics3D

You should also explore the available vignette (a work in progress!) or contribute your own (contributions are very welcome!). To view the Lithics3D vignette:

vignette("Lithics3D")

lithics3d's Issues

Implement the edge angle measurement approach of Valletta et al. (2020)

Add option to measure edge angles as per Valletta et al. (2020) - https://doi.org/10.1007/s12520-019-00954-w

Fix mesh_tmap_plot

There are numerous known issues with the mesh_tmap_plot function, and they should be fixed:

• poor input checking
• seemingly bogus artifacts in the output (e.g., with mesh_tmap_plot(mesh_tmap(demoFlake1$mesh, base.res = 0.1, ld.cutoff = 0.05)$tmap, font_size = 12))
• no unit tests

e2sIntersect not working as expected

The function no longer produces sensible output on the reduced meshes after replacing the original ptOnSeg with coords_onseg.

mesh_segment_by_path silently drops mesh faces

The function drops some faces that clearly should not be dropped. A reproducible example:

mesh <- demoSphere
pois <- t(demoSphere$vb)[c(1, 20, 30, 45), 1:3]
mesh_path <- sPathConnect(pois, mesh, closed = TRUE)
res <- mesh_segment_by_path(mesh, mesh.path = mesh_path)

#' No purple face from the un-split mesh should be visible, but one is because the split
#' mesh segments don't cover the whole surface (i.e., a face was dropped)
shade3d(mesh, col = "purple", alpha = 0.9)
shade3d(res[[1]], col = "red")
shade3d(res[[2]], col = "green")

Implement the edge angle measurement procedure of Schunk et al. (2023)

Enable computing edge angles as per the '2-lines' and 'best fit' procedure of Schunk et al. (2023).

coords_onseg - incorrect output

The following input should produce one TRUE value, but the output is FALSE, FALSE:

seg <- data.frame(x = c(-7.249440, -7.282816),
y = c(0.5743027, 0.9284002),
z = c(502.5920, 502.8661))
coords <- data.frame(x = c(-7.259582, -7.455739),
y = c(0.6819025, 2.7629832),
z = c(502.6753, 504.2863))
coords_onseg(coords, seg, tol = 0.01) # FALSE FALSE

dist_pt2l(coords, seg) # Not perfect, but clearly within a reasonable threshold of the line

Plot to visualize - one point is clearly on the segment:

lines3d(seg, col = "red")
points3d(coords, col = "blue")

Reduce size of included demo meshes.

The included data files are too large (~30 MB with compression), well above the CRAN limit. I don't think there is a good reason for the included demo meshes to be that big, so: a) reduce the meshes to something more reasonable, and b) make sure everything (e.g., examples) still works as expected.

Tests and better documentation needed for the edgeAngles function

There are currently no unit tests for the edgeAngles function, and the documentation is not very clear. This needs fixing as soon as possible, since the plan is to revisit and substantially enhance this function in the near term.

Tests needed for e2sIntersect and edgesOnPlane

There are currently no tests for these functions.

Fix ptOnSeg

The function was left in an unfinished state back in 2019. The d.t parameter is currently ignored and the output is not tested, so that needs fixing; the function should also be renamed to conform to current naming standards.

Errors with build checks on Mac OS (check_mac_release())

A test in test-mesh_mark_pois.R (expect_known_scene("mesh_mark_pois_demosphere_vp1", close = TRUE)) fails on the Mac OS builder (https://mac.r-project.org/macbuilder/submit.html), apparently due to a trivial and inconsequential change in material color for a known scene. Some warnings are also generated.

Implement the edge angle measurement approach of Yezzi-Woodley et al. (2021)

Enable calculating edge angles as per Yezzi-Woodley et al. (2021) - https://doi.org/10.1007/s12520-021-01335-y

Apply consistent approach to function deprecation

Functions that are deprecated should be documented in a similar way:

• lifecycle tag - deprecated or superseded.
• title and description: (Deprecated) - as done in align_pca.R.
• description: explain rationale for deprecation and what function takes over, if any, with a direct link to the latter. If possible, provide an example of how the same functionality can be obtained through the function that replaces it.
• Add a document where this process is documented (for the future).

Discrepancy between output of edge_angles_yw and the Virtual Goniometer Meshlab plugin

There is a major (18 degrees) difference in the outputs of the edge_angles_yw and Virtual Goniometer Meshlab plugin with the following inputs:

mesh <- Rvcg::vcgUpdateNormals(demoFlake2$mesh)
res <- edge_angles_yw(mesh = mesh, poi = data.frame(x = c(16.395319), y = c(51.524971), z = c(409.201294)), radius = 2.994467, lambda = 2)

The angle computed above is 121.166, while the Meshlab plugin returns an angle of 139.2329.