;+
; NAME:
;	vu_point_source
; PURPOSE:
;	Manipulates structure used for plotting of point sources.
; CATEGORY:
;	/sat/idl/util/vupack
; CALLING SEQUENCE:
	FUNCTION vu_point_source, point_sources, update, $
		elongation	= elongation	, $
		name		= name			, $
		time		= time			, $
		location	= location		, $
		ips_speed	= ips_speed		, $
		ips_glevel	= ips_glevel	, $
		brightness	= brightness	, $
		pb			= pb			, $
		field		= field			, $
		size_base	= size_base		, $
		size_ratio	= size_ratio	, $
		xy_pixel	= xy_pixel		, $
		degrees		= degrees		, $
		create		= create
; INPUTS:
;	pnt 		array; type: sky_point_source structure
; OPTIONAL INPUT PARAMETERS:
;	update		if it exists, used to update a field in the input
;				structure (as indicated by appropriate keyword)
;	create=create
;				scalar; type: integer
;			 	only used if 'update' exists. Creates a new structure
;				of 'create' elements (destroying the input 'pnt' structure).
;
;	/degrees	if set then all angles are in degrees, instead of radians
;
;	/name		return or set name of source
;	/time		return or set time of observation
;	/location	return or set locatione of source in sky as RA,dec
;
;	/ips_speed	return or set IPS speed
;	/ips_glevel return or set IPS g-level
;	/brightness return or set Thomson scattering brightness
;	/pb 		return or set pB
;
;	/size_ratio if set in combination with /ips_speed, /ips_glevel, /brightness
;				or /pb, then the increase of the circle size per data unit
;				is returned. In href=PlotEarthSkymap= this is used to increase
;				the circle size for larger differences between point source
;				and background map.

;	/size_base	return or set the base size (minimum size) of circle used
;				for plotting point sources
;
;	field=field scalar; type: integer
;				return or set the indicated field in the 'pnt' structure
;				This overrides any of the above keywords.
; OUTPUTS:
;	Result 		if the input 'update' argument does NOT exist, then
;				a field from the 'pnt' structure (or a quantity
;				derived from one or more fields) as indicated by
;				keyword settings, is returned
;				if the input 'update' argument DOES exist, then
;				the modified structure is returned
; OPTIONAL OUTPUT PARAMETERS:
; INCLUDE:
	@compile_opt.pro		; On error, return to caller.
; EXTERNAL:
;	sky_point_source__define
; CALLS:
;	InitVar, IsType, ToDegrees, sphere_distance, CvSky, big_eph, jpl_body
; PROCEDURE:
;	Mostly intended to hide the exact structure of the point source
;	structure from users.
; MODIFICATION HISTORY:
;	SEP-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;-

InitVar, name 		, /key
InitVar, time		, /key
InitVar, location	, /key
InitVar, elongation	, /key
InitVar, ips_speed  , /key
InitVar, ips_glevel , /key
InitVar, brightness , /key
InitVar, pB 		, /key

InitVar, size_base	, /key
InitVar, size_ratio , /key
InitVar, xy_pixel	, /key

dpm = ToDegrees(degrees=degrees)

CASE IsType(update, /defined) OF
0: BEGIN

	CASE 1 OF

	IsType(field,/defined): out = point_sources.(field)

	name		: out = point_sources.name
	time		: out = point_sources.tt
	location	: out = point_sources.pp
	size_base	: out = point_sources.sz
	ips_speed	: IF size_ratio THEN out = point_sources.szvv ELSE out = point_sources.vv
	ips_glevel	: IF size_ratio THEN out = point_sources.szgg ELSE out = point_sources.gg
	brightness	: IF size_ratio THEN out = point_sources.szbb ELSE out = point_sources.bb
	pb			: IF size_ratio THEN out = point_sources.szpb ELSE out = point_sources.pb
	xy_pixel	: out = point_sources.xy

	elongation	: out = sphere_distance(degrees=degrees	, $
			CvSky(point_sources.tt, from_equator=point_sources.pp/dpm, /to_ecliptic, degrees=degrees, /silent), $
			(big_eph( reform(point_sources.tt)		, $
				body	= jpl_body(/sun  ,/string)	, $
				center	= jpl_body(/earth,/string)	, $
				/to_ecliptic	, $
				/to_sphere		, $
				/precess		, $
				/onebody		, $
				/silent 		, $
				degrees = degrees) )[0:1,*]	)
	ELSE		: out = point_sources
	ENDCASE

	IF location OR size_base OR size_ratio THEN out /= dpm
END
1: BEGIN

	; All angles are stored in the structure in degrees. Make sure to convert
	; from units implied by keyword /degrees.to degrees

	CASE IsType(create,/defined) OR IsType(point_sources,/undefined) OF
	0: out = point_sources
	1: BEGIN
		InitVar, create, n_elements(update)

		out = replicate( { vu_point_source }, create )
		out[*].xy = [-1,-1]		; Used by PlotEarthSkymap to set pixel locations of sources

		out[*].sz = 2.5

		out[*].szvv = 2.5/600.0
		out[*].szgg = 2.5/1.0
		out[*].szbb = 2.5/1.0
		out[*].szpb = 2.5/0.1
	END
	ENDCASE

	IF location OR size_base OR size_ratio THEN update *= dpm

	CASE 1 OF

	IsType(field, /defined): out[*].(field) = update

	name		: out[*].name = update
	time		: IF n_elements(update) EQ 1 THEN out[*].tt = replicate(update,size(out[*].tt,/dim)) ELSE out[*].tt = reform(update,size(out[*].tt,/dim))
	location	: out[*].pp	  = update
	size_base	: out[*].sz   = update
	ips_speed	: IF size_ratio THEN out[*].szvv = update ELSE out[*].vv = update
	ips_glevel	: IF size_ratio THEN out[*].szgg = update ELSE out[*].gg = update
	brightness	: IF size_ratio THEN out[*].szbb = update ELSE out[*].bb = update
	pb			: IF size_ratio THEN out[*].szpb = update ELSE out[*].pb = update
	xy_pixel	: out[*].xy	= update

	ELSE		: out[*] = update
	ENDCASE

	IF location OR size_base OR size_ratio THEN update /= dpm

END
ENDCASE

RETURN, out  &  END