/*******************************************************************************
** Copyright (c) 1992-2025 MAK Technologies, Inc
** All rights reserved.
*******************************************************************************/
//! \file topoCoord.h
//! \ingroup matrix
//! \brief This file contains useful functions for geocentric to 
//! topographic conversions.
#pragma once

#include "geodeticCoord.h"
#include "LibMatrix.h"

#ifdef DtUSE_UTILITIES_NAMESPACE
namespace DtUSE_UTILITIES_NAMESPACE
{
#endif

//! Any point on the globe can be used to specify the origin of a 
//! specific topographic coordinate system.  In VR-Link, a topographic
//! frame is defined with the positive X axis pointing north, the 
//! positive Y axis pointing east, and the positive Z axis pointing down.

//! From latitude and longitude, we can produce the rotation matrices
//! that rotate between geocentric and topographic-down orientations.
//! VR-Link uses post-multiplication for its rotation matrices. For 
//! example, the matrix produced by DtLatLon_to_TopoToGeoc can be used
//! to rotate a topographic vector to a geocentric vector like this:
//!     DtDcmVecMul( topoToGeoc, Vtopo, Vgeoc );
DT_DLL_MATRIX void DtLatLon_to_TopoToGeoc(
   const DtGeodeticCoord& g, DtDcmRef topoToGeoc );

//! The matrix produced by DtLatLon_to_GeocToTopo can be used
//! to rotate a geocentric vector to a topographic vector like this:
//!      DtDcmVecMul(geocToTopo, Vgeoc, Vtopo);
DT_DLL_MATRIX void DtLatLon_to_GeocToTopo(
   const DtGeodeticCoord& g, DtDcmRef geocToTopo );

//! This function can initialize a DtCoordTransform so that it can provide
//! transformations between the geocentric coordinate system, and a
//! particular topographic coordinate system defined by latitude and 
//! longitude. Latitude and longitude should be in radians.
DT_DLL_MATRIX void DtGeocToTopoTransform(
   double latitude, double longitude, DtCoordTransform* geoc2topo );

//! This utility function returns your heading in radians from your geocentric 
//! location and orientation. It automatically does the transformation to 
//! topographic in order to do this conversion.
DT_DLL_MATRIX double DtGetHeadingFromGeocentric( DtVector geocLoc, DtTaitBryan geocOri );

//! This utility function returns your pitch in radians from your geocentric 
//! location and orientation. It automatically does the transformation to 
//! topographic in order to do this conversion.
DT_DLL_MATRIX double DtGetPitchFromGeocentric( DtVector geocLoc, DtTaitBryan geocOri );

//! This utility function returns your roll in radians from your geocentric 
//! location and orientation. It automatically does the transformation to 
//! topographic in order to do this conversion.
DT_DLL_MATRIX double DtGetRollFromGeocentric( DtVector geocLoc, DtTaitBryan geocOri );


#ifdef DtUSE_UTILITIES_NAMESPACE
}
#endif



