DatumPointPolar.h

/*
 *  DatumPointPolar.h
 *  
 *  Created by Mike Fuller on 04/02/08.
 *  Copyright 2008. All rights reserved.
 *
 *	PURPOSE:
 *	Used for data representing points recorded within circular plots. 
 *	Assumes all data coordinates fall into one of the four quadrants of the unit 
 *	circle, defined by the angle generated by the position of a point on the 
 *	circumference of the circle. The origin of the plot occurs at 0,0 and:
 *	
 *	x = 1, y = 0 for theta = 0 degrees or 0 radians or 2 Pi radians
 *	x = 0, y = 1 for theta = 90 degrees or 1/2 Pi radians
 *	x = -1, y = 0 for theta = 180 degrees or Pi radians
 *	x = 0, y = -1 for theta = 270 degrees or 3/2 Pi radians
 *
 *	This class can be used to store and manipulate data representing points 
 *	in the plane, such as trees, which are sampled using circular plots.
 *	Two member-variables, angle and dist2ctr, allow one to keep track of the  
 *	empirical spatial positions of different points using polar coordinates.  
 *	Functions are included for transforming x-y coordinate pairs into theta  
 *	angles on the unit circle. When combined with the radius of the plot, this
 *	allows groups of points to be cataloged using their theta angles. 
 *
 *	NOTES:
 *	While the initial values of the x,y coordinates are stored when the
 *	parameterized constructor is called for a DatumPointPolar object, they
 *	are otherwise not stored or tracked explicitly as variables when 
 *	initialized. Instead, they are calculated on the fly as needed using 
 *	the relationship between the angle and coordinates of polar points on
 *	the unit circle. Thus, the maximum value of x or y is explicitly 1.0,
 *	while the maximum angle is 360 degrees. The value of the coordinates
 *	are calculated from the angle theta using standard trigonometic 
 *	functions and the value of Pi. The x,y coordinates of each point are 
 *	coded internally as a percentage of the distance to the plot center 
 *	(dist2ctr). When accessed by a calling object, the x,y coordinates are 
 *	rescaled to their original values (i.e. not unit circle).
 *
 *	IMPORTANT
 *	**	Because the functions get_Xcoord() and get_Ycoord() have been  
 *		redefined from the base class, USE WITH CARE. 
 *
 *	**	The functions set_Xcoord(double) and set_Ycoord(double) have not 
 *		been redefined from the base class and SHOULD NOT BE USED as they
 *		are not defined in the proper context within the base class for 
 *		use in the present class. If the program detects an attempt to
 *		use these functions, it will abort the program run! 
 *		Beware!
 *
 */

#ifndef DATAPOINTPOLAR_H
#define DATAPOINTPOLAR_H
#include <vector>
#include "DatumPoint.h"

namespace MMFdata
{
	
	//used for calculating angle of polar point
	const double PI = 3.14159;
	
	class DatumPointPolar : public DatumPoint
		{
		public:
			//identitynumber set to -1
			//dist2ctr and x-coordinate set to 1.0
			//y-coordinate and angle set to zero
			DatumPointPolar(); 

			//sets values of member variables to arguments 
			//calculates dist2ctr and angle from x,y coordinates
			//rescales coordinates to unit circle
			//calculates theta angle from coordinates
			DatumPointPolar(int ID, int spp, int value_int, double value_dec, 
							double dbl, double X, double Y);
		
			//copy constructor
			DatumPointPolar(const DatumPointPolar& dppObject);
				
			//destructor (virtual because nothing to destroy)
			virtual ~DatumPointPolar();
			
			// ACCESSOR FUNCTIONS
			
			//returns empirical value of X_coordinate
			//redefined from base class to account for unit circle scaling
			double get_Xcoord() const;
			
			//returns empirical value of X_coordinate
			//redefined from base class to account for unit circle scaling
			double get_Ycoord() const;
			
			//returns pointer to 1-D array holding x and y coordinates
			//returns empirical values
			//array[0] = x, array[1] = y
			vector<double> get_XYcoords();
			
			//returns dist2ctr value
			double get_dist2ctr() const;
			
			//returns theta angle value between 0 and 360 degrees
			//uses math.h
			double get_angle() const;	 
			
			// MUTATOR FUNCTIONS
			
			//setting x-coordinate and y-coordinate 
			//deliberately not defined for this derived class
			
			//Redefined from base class. Inserts new values for x,y coordinates.
			//Also changes the dist2ctr and angle to account for change in coordinates.
			void set_XYcoords(double XYdat[2]);
			
			//sets dist2ctr value (distance from circle-plot center)
			void set_dist2ctr(const double distance);
			
			//sets value of angle and changes values of X,Y coordinates
			//to account for change in angle
			void set_angle(double anglen);
			
			//Redefined from base class to account for unit-circle scaling
			//Adds to dist2ctr value of X coordinate, effectively moving it to the right or left 
			//(if negative value)
			//Will generate warning if added_value causes X coordinate to exceed 1.0
			void shift_dppX(const double added_value);
			
			//Redefined from base class to account for unit-circle scaling
			//Adds to value of Y coordinate, effectively moving it up or down (if negative value)
			//Will generate warning if added_value causes Y coordinate to exceed 1.0
			void shift_dppY(const double added_value);
		
			//converts DatumPointPolar object to DatumPoint object 
			//Restores empirical values of XY coordinates
			DatumPoint dpp2dp();
				
			DatumPointPolar& operator =(const DatumPointPolar& rhs);
			bool operator ==(const DatumPointPolar& rhs) const;


		private:
			double dist2ctr;  //radius of (inner) circle on which point falls (point is on circumference)
							  //dist2ctr is usually less than the radius of the empirical plot.
			double angle;     //angle of point relative to zero radians position
	
		protected:		
			//sets angle of point based on x,y coordinates
			void calc_angle_fromcoords();
			
			//uses Pythagorean theorem to calculate dist2ctr from x,y coordinates
			//The result represents the radius of the circle on which the point lies.
			void calc_dist2ctr_fromcoords();
			
			//scales values of x,y coordinates to unit circle (dist2ctr = 1)
			void scale_XY_toUnitCircle();
			
		};
	
} //MMFdata

#endif  //DATAPOINTPOLAR_H