# Using molaR

The R package molaR provides functions that allow the user to quantitatively measure and graphically represent dental surface complexity. The following is a demonstration of the major functions in molaR.

molaR utilizes three-dimensionally embedded triangular mesh files. These files can be imported to R using the “read.ply” function from the geomorph package. Here, we use 3D scan data of two teeth (details???) included in the molaR package as the objects “ex_tooth1” and “ex_tooth2”.

``````library(molaR)
summary(ex_tooth1)
``````
``````##               Length Class  Mode
## vb            20472  -none- numeric
## it            30000  -none- numeric
## primitivetype     1  -none- character
## material          0  -none- NULL
## normals       20472  -none- numeric
``````

## Dirichlet's normal surface energy (DNE)

Dirichlet's normal surface energy can be calculated with the DNE function. The face energy density values calculated can then be projected onto a three dimensial surface image using DNE3d.

``````DNE1 = DNE(ex_tooth1)
``````
``````## [1] "Total Surface DNE"
## [1] 174.5563
``````
``````DNE3d(DNE1) #you will need to zoom out to see the whole tooth in an html graphics window
``````

Note that the color scale on this plot is set relative to the values of the tooth. When comparing multiple teeth, setting the scale manually will ensure it is the same for all teeth. This is done with the “setRange” parameter.

``````DNE2 = DNE(ex_tooth2)
``````
``````## [1] "Total Surface DNE"
## [1] 310.6514
``````
``````DNE3d(DNE2, setRange = c(0, 1.3))
``````
``````DNE3d(DNE1, setRange = c(0, 1.3))
``````

The reported “Total Surface DNE” excludes boundary faces and the faces with the highest 0.1% energy densities. Both sets of faces can be accessed through the list object created by the DNE function

``````head(DNE1\$Edge_Values)
``````
``````##     DNE_Values  Face_Areas
## 803  0.1526292 0.002044632
## 804  0.7491742 0.001976580
## 807  0.6422248 0.010534145
## 809  0.8400568 0.008359820
## 819  0.5944883 0.006355737
## 821  0.3320267 0.011879445
``````
``````head(DNE1\$Outliers)
``````
``````##      DNE_Values   Face_Areas
## 1492   1282.183 6.978101e-05
## 1495   1296.258 6.506020e-05
## 1784   2101.342 6.082532e-05
## 2482    896.660 1.502099e-04
## 2572   5112.554 6.119452e-05
## 2574   5026.874 1.786014e-06
``````

## Relief Index (RFI)

The RFI function will caculate the relief index of a tooth, the three dimensional surface area of the tooth crown, and the area of the tooth crown's two dimensional foot print.

``````RFI1 = RFI(ex_tooth1)
``````
``````## [1] "RFI"
## [1] 0.4773583
## [1] "Three D Area"
## [1] 118.6806
## [1] "Two D Area"
## [1] 45.68267
``````

The three dimensional surface and its two dimensional footprint can be plotted adjacently using the RFI3d function.

``````RFI3d(RFI1)
``````

## Orientation Patch Count (OPC)

The OPC function bins each triangular face on a mesh surface (tooth) into one of 8 groups based on the x-y orientation of the face, then determines the number of resulting “patches” on the tooth. These patches can be visualized using the OPC3d function.

``````OPC1 = OPC(ex_tooth1)
``````
``````## \$`total patches`
## [1] 113
##
## \$directions
##   [,1]
## 3   14
## 2    9
## 4   16
## 5   17
## 8   14
## 6   15
## 7   13
## 1   15
``````
``````OPC3d(OPC1)
``````

By default, the OPC function counts any patch consisiting of two or more faces. This can be changed using the minimum_faces parameter or overriden by the minimum_area parameter, which sets the minimum percent (Proportion???) of total surface area a patch must contain to be counted.

``````OPC2 = OPC(ex_tooth1, minimum_faces = 20)
``````
``````## \$`total patches`
## [1] 41
##
## \$directions
##   [,1]
## 3    6
## 2    4
## 4    6
## 5    5
## 8    5
## 6    6
## 7    5
## 1    4
``````
``````OPC3 = OPC(ex_tooth1, minimum_area = 0.01)
``````
``````## \$`total patches`
## [1] 20
##
## \$directions
##   [,1]
## 3    1
## 2    2
## 4    3
## 5    3
## 8    3
## 6    2
## 7    4
## 1    2
``````

Due to the somewhat arbitrary boundaries of bins, differences in specimen orientation during analysis can result in minor variations of OPC. The OPCr function attempts to account for this by iteratively rotating the tooth (default is 8 iterations between 0 and 45 degrees of rotation) and calculating the OPC of each iteration. A mean OPC is reported.

``````OPCr1 = OPCr(ex_tooth1)
``````
``````## [1] 173
``````
``````OPCr2 = OPCr(ex_tooth1, Steps = 5, stepSize = 9, minimum_faces = 2) #the minimum_faces and minimum_area parameters are passed to each iteration of OPC
``````
``````## [1] 173
``````

The object returned by OPCr also contains the OPC values and degrees of rotation for each iteration.

``````OPCr1\$Each_Run
``````
``````##      Degrees_Rotated Calculated_OPC
## [1,]           0.000            180
## [2,]           5.625            179
## [3,]          11.250            198
## [4,]          16.875            172
## [5,]          22.500            161
## [6,]          28.125            167
## [7,]          33.750            155
## [8,]          39.375            172
``````
``````OPCr2\$Each_Run
``````
``````##      Degrees_Rotated Calculated_OPC
## [1,]               0            180
## [2,]               9            187
## [3,]              18            180
## [4,]              27            159
## [5,]              36            159
``````