\name{fiber.angle}
\alias{fiber.angle}
\title{
Calculating the orientation of muscle fibers}
\description{
Calculating the orientation or pennation angle of individual muscle fibers. This function can calculate fiber angles around a central axis (x, y or z) or in reference to a particular "view" (plane). Fiber data can optionally be aligned to a line of action (tendon, line between origin and insertion points, etc.) to calculate pennation angle.
}
\usage{
fiber.angle(fib.list, axis, reference = "axis", 
endpoints=NULL, end.to.end=FALSE)
}
\arguments{
  \item{fib.list}{
A list of muscle fiber paths generated by good.fibes or from the various cleaning and processing function (must contain $fiber.points).
}
  \item{axis}{
The axis around which angles will be calculated as a deviation from. Default is 3 (z). This axis is treated as the "z" axis for "plane" options.
}
   \item{reference}{
Should the orientation angles be calculated about an axis (specified by "axis") or in reference to a plane ("plane.xz" "plane.yz", or "plane.xy", where z is the value of "axis"). When calculating pennation angles, reference = "line.of.action" and argument "endpoints" should be supplied.
}
\item{endpoints}{
An optional 2X3 matrix generated by \code{\link{find.endpoints}}. When supplied, data is centered on the first endpoint and rotated such that the second lies along the z axis, such that angles are calculated in reference to a straight line between the two endpoints.
}
\item{end.to.end}{
Should the angle be calculated over the entire fiber (FALSE) or based on just the enpoints of the fiber (TRUE).
}
}
\details{
Fiber angle is calculated from the eigenvectors of a Principal Component Analysis of the fiber coordindates using \code{\link{prcomp}}.
}
\value{
A vector of angles in degrees corresponding to each fiber in the original list}
\references{
Arbour, J. 2023. GoodFibes: an R package for the detection of muscle fibers from diceCT scans. \emph{Integrative Organismal Biology} 5(1): obad030.

Katzke, J., Puchenkov, P., Stark, H., and Economo, E. 2022. A Roadmap to Reconstructing Muscle Architecture from CT Data. \emph{Integrative Organismal Biology} 4(1): 1-16.

Sullivan, S., McGechie, F., Middleton, K., and Holliday, C. 3D Muscle Architecture of the Pectoral Muscles of European Starling (Sturnus vulgaris).\emph{Integrative Organismal Biology} 1(1):1-18.

}
\author{
J. Arbour
}
\seealso{
\code{\link{fiber.lengths}}
}
\examples{

\donttest{
olddir<-getwd()

data(ant.final)
fangle<-fiber.angle(ant.final,3)
fangle

cols<-color.scale(fangle, c("blue", "red"))
muscle.plot.stl(ant.final, cols=cols, df = 1)

setwd(olddir)
}
}
