R/edgedir1D.R

In arnejohannesholmin/sonR: Library for reading, processing and converting sonar data to the TSD format

#*********************************************
#*********************************************
#' Calculates the edge points of an ecousounder based on the CTD-data, creating circular volume elements centered around the vertical upwards direction (note that the resulting data needs to be rotated back to the direction of the beams outside of this function). !!!Only one time step is treated!!!!
#'
#' @param data  is the list of TSD inputs as returned from read.TSD (must contain ""dira" and "dire", and CTD-data).
#' @param esnm  is the name of the acoustical instrument, given as a four character string. See sonR_implemented() for the implemented systems. May be given in 'data', and in lower case.
#' @param seabed  is the z-coordinate of the sea bed, usually provided by echo sounder data. Soundbeams reflected from the sea bed or the surface are reflected at the incidence angle.
#' @param rot  is 1 if simple rotation using cosine and sine is to be used, and 2 if the function rotate() is to be used in the rotation. Times for the different methods (tested on MacBook Pro dual 2.8 GHz, 2010-02-09, with other applications running):
#' @param compensation  is a vector of string giving which rotation values that are compensated for in the sonar. Only c("pitch","roll") is available for the current version. Used in soundbeam.TSD.
#' @param ideal  is TRUE to represent the simple case where the speed of sound 'data$asps' is invariant of depth.
#' @param ... Used for robutness.
#'
#' @return
#'
#' @examples
#' \dontrun{}
#'
#' @importFrom TSD car2sph
#'
#' @export
#' @rdname edgedir1D
#'
edgedir1D<-function(data, esnm=NULL, seabed=-12000, rot=1, compensation=c("pitch","roll"), ideal=TRUE, ...){
		
	############ AUTHOR(S): ############
	# Arne Johannes Holmin
	############ LANGUAGE: #############
	# English
	############### LOG: ###############
	# Start: 2015-03-26 - Clean version.

	
	##################################################
	##################################################
	##### Preparation #####
	# Extract the name of the acoustic instrument:
	if(is.null(esnm)){
		esnm=data$esnm[1]
		}
	else if(!identical(tolower(data$esnm[1]),tolower(esnm))){
		warning("The value of 'esnm' given in 'data' ignored")
		}
	# If 'rect' is not in 'data', issue a warning:
	if(length(data$rect)==0){
		warning("The list 'data' must contain the logical vector 'rect' defining which beams are rectangular (FALSE for circular/elliptical beams)")
		}
	
	
	##### Execution #####
	# Run along the beams and get the radial distances to the voxels:
	out_c=car2sph( soundbeam.TSD(data, ind=!data$rect, cs="v", seabed=seabed, rot=rot, compensation=compensation, ideal=ideal, rpos="edge", drop.out=FALSE, plot=FALSE), list.out=FALSE, nonneg=TRUE)
	
	D1 = max(data$lenb[!data$rect])+1
	#D3 = length(data$dire[!data$rect])
	#D2 = length(data$dire[!data$rect])
	D2 = sum(!data$rect)
	dim(out_c) = c(D1, D2, 3)
	
	# Convert from eqba to the angle out to the edge of the circular voxels:
	if(length(data$eqba)==0){
		stop("'eqba' must be given for circilar voxels (voxels!=\"rect\")")
		}
	eqba_ang=acos(1-10^(data$eqba/10)/(2*pi))
	# Create spherical segments that point vertically upwards, thus utilizing the elevation angle. The data generated by runif.sph() should be rotated back to the original direction of the beams:
	out_r=cbind(r0=c(out_c[-D1,,1]), r1=c(out_c[-1,,1]), theta0=0, theta1=2*pi, phi0=0, phi1=rep(eqba_ang, each=D1-1))
	
	
	##### Output #####
	# Return a list of the edgepoints of the circular voxels:
	return(list(circ=out_c))
	##################################################
	##################################################
	}