;+
; NAME:
;	smei_star__define
; PURPOSE:
;	Defines structure to store fit parameters for stars
; CATEGORY:
;	camera/idl/star
; CALLING SEQUENCE:
	PRO smei_star__define
; INPUTS:
;	(none)
; OUTPUTS:
;	(none)
; INCLUDE:
	@compile_opt.pro		; On error, return to caller
; RESTRICTIONS:
;	If this structure is modified then the format statements in
;	href=smei_star_formatpnt= need to be updated accordingly.
; PROCEDURE:
;	The standard star is defined as a 200 x 200 array with bins
;	of 0.025 x 0.025 degrees (5 x 5 degree total). 
;	The skymaps have bins of 0.1 x 0.1 degrees.
;
;	When a star is fitted to the 'standard star' locations in
;	a box of 50 x 50 bins (5 x 5 degrees) around the star are mapped into the
;	'standard star' map where 'standard brightnesses' are determined
;	by linear interpolation on the 'standard star' array. Fitting
;	the star involves matching observed 50 x 50 observed skymap brightnesses
;	against the 50 x 50 'standard brightnesses'.
;
;	The fit is done using skybins inside an area defined by the core PSF, and
;	(if wing_radius is used, instead of bkgnd_radius) additional bins
;	extending out to the selected wing_radius).
;
;	Let there be 'n' 0.1 x 0.1 bins in the skymap inside the (extended) PSF,
;	and let the skymap brightness in these bins be
;	(1)		v(i)					i=1,n
;	These values can be symbolically represented as:
;	(2)		v(i) = a(i) + I(i)		i=1,n
;	where a(i) is the background component, and I(i) the brightness
;	attributed to the star.
;
;	The locations in the skymap are mapped into the 'standard star' reference
;	frame. By linear interpolation the 'standard brightnesses' are:
;	(3)		I_std(i)		i=1,n
;
;	The fitting procedure generates an lsq 'model' for the star from
;	'standard star' values:
;	(4)		v_model(i) = A(i) + B * I_std(i)
;
;	Here A(i) represents a planar fit to  the background, and B is the
;	star brightness normalized to the 'standard star' brightness.
;	These fit quantities are stored in structure tags:
;			back_const
;			back_slope
;			bright
;
;	Let the extended PSF, mapped to the 'standard star' reference frame,
;	cover a total of 'N' 0.025 x 0.025 bins and let the 'standard
;	brightness' in these bins be
;	(5)		J_std(N)		i=i,N
;
;	The total number of ADUs in this area then is
;	(6)		T(std) = Sum(i=1,N) {J_std(i)}
;
;	A similar sum can be defined from (3), based on 0.1 x 0.1 deg bins:
;	(7)		U(std) = Sum(i=1,n) {I_std(i)}
;
;	Since
;	(8)		N = (0.1/0.025)^2 x n = 16 x n
;	it follows
;	(9)		U(std) = T(std)/16
;	or
;			U(std) x 0.1^2 = T(std) x 0.025^2
;
;	The quantity T(std) x 0.025^2 is stored in the structure tag 'total_adus'.
;	It is calculated in href=smei_star_stdmaps= in the 'standard star'
;	reference frame (the right side of Eq. (9)).
;
;	There are two indirect ways to calculate the quantity 'B' in (4).
;	The first one is fairly trivial. v_model in Eq (4) is calcaluted as a
;	50 x 50 array, matching the box in the skymap. Looking at Eqs. (4)
;	and (9):
;	(10)	B1 = Sum(i=1,n) {v_model(i)-A(i)) / U(std)
;
;	The second is an estimate based on the actual data 'v(i)' in Eq. (1),
;	and assuming that the fit worked:
;
;	(11)	Sum(i=1,n) {v(i)} = Sum(i=1,n) {v_model(i)}
;
;	From (10) and (11) it follows:
;
;	(12)	B2 = Sum(i=1,n) {v(i)-A(i)} / U(std)
;
;	B1 is stored in tag 'bright_mdl'; B1 is stored in tag 'bright_raw'.
;
;	If the bins used in the lsq fit would be the same set of bins used
;	to calculate the sum in Eq. (10), then B1 would be identical to
;	B in Eq. (4). For a number of reasons only a subset of the bins in
;	Eq (1) are actually	used in the lsq fit. So B1 and B will not be
;	identical.
;
;	B2 in some sense is an indicator of the quality of the lsq fit. For
;	a perfect fit, B2 would be the same as B (Eq. 4). In reality, there
;	are systematic differences between B2 and B that are not understood.
; MODIFICATION HISTORY:
;	AUG-2006, Paul Hick (UCSD/CASS)
;		Extracted from smei_star_fit
;	NOV-2006, Jordan Vaughan (UCSD; jtvaugha@ucsd.edu)
;		Added gain field to stars_fit
;	MAY-2007, Paul Hick (UCSD/CASS)
;		Changed scalar fovxangle to 2-element array fovangle
;		Added 2-element array dfovangle
;	JUL-2007, Paul Hick (UCSD/CASS)
;		Added psfstretch, renamed dfovangle to dpsfstretch
;	FEB-2008, Paul Hick (UCSD/CASS)
;		Added "remove" entry.
;	NOV-2011, Paul Hick (UCSD/CASS)
;		Expanded information in header considerably.
;	JUL-2012, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;		Added structure key 'total_area'
;-

stars_fit = {smei_star  	, $

	name		: ''		, $ 							; Name of star
	radec		: [0.0,0.0] , $ 	;'RA','dec'				; RA/dec of star from catalogue

	maptype 	: ''		, $ 							; Type of map where star was fitted
	camera		: 0 		, $ 	;'C'					; Camera
	ccd_mode	: 0			, $		;'M'					; Mode

	; Based on low-res maps

	time		: ''		, $ 	;'YYYY_DOY_hhmmss'		; Time of observation (may need correction near edge of map)
	psfangle	: 0.0 		, $ 	;'PSFangle'				; PSF rotation angle
	fovangle	: [0.0,0.0] , $ 	;'FOVXangle','FOVYangle'; Angle of centroid from camera optical axis along
	psfstretch	: [0.0,0.0] , $		;'cosFOVX','cosFOVY'	; long and narrow FOV dim

	; Camera gain

	gain		: 0.0		, $		;'gain'					; Camera gain constant

	; Based on hi-res maps

	name_close	: ''		, $ 	;'close'				; Name of nearby brighter star if star was not fitted separately
															; (if a name is in here there won't be any fit parameters)
	total_area	: 0.0		, $		; 'Astd'				; PSF area (incl. wing if wing_radius is used)
	total_adus	: 0.0		, $		; 'Istd'				; PSF adus (incl. wing if wing_radius is used)
	bright_raw	: 0.0		, $ 	; 'Isky/Istd'			; Mean adus inside sky PSF after background subtraction
	bright_mdl	: 0.0 		, $ 	; 'Imdl/Istd'			; Mean adus inside mdl PSF after background subtraction

	; Fit results

	bright		: 0.0 		, $ 	; 'I/Istd'				; Fitted brightness scale
	back_const	: 0.0		, $ 	; 'BckCnst'				; Fitted background
	back_slope	: [0.0,0.0]	, $ 	; 'BckRAslope','BckDecslope' ; RA/dec slope of background fit (ADUs/degree)
	n_bkgnd 	: 0 		, $ 	; 'nbkg'				; # Pixels inside background area
	n_fitpsf	: 0 		, $ 	; 'npsf'				; # Pixels inside PSF
	stdev_bkgnd : 0.0 		, $ 	; 'sigbkg'				; Standard deviation of background residual
	stdev_psf	: 0.0 		, $ 	; 'sigpsf'				; Standard deviation of star residual inside PSF
	cvfit		: 0.0		, $ 	; 'corr'				; Correlation coefficient of fit
	dradec		: [0.0,0.0]	, $ 	; 'dRA','dDec'			; Correction to RA/dec of catalogue location
	dpsfangle	: 0.0		, $		; 'dPSFangle'
	dpsfstretch	: [0.0,0.0] , $ 	; 'dcosFOVX','dcosFOVY'	; Correction to direction cosine angles
	psfwidth	: [0.0,0.0] , $ 	; ,'widRA','widDec'		; Estimate of PSF halfwidth perpendicular and along PSF symmetry axis

	; Leftover

	remove	 	: 0 		, $ 	; 'X'					; Set to 1 if subtracted from skymap
	done		: 0 		$	 							; Indicates that star was fitted (always 1)
}

RETURN  &  END