----- file created by makedoc on: Thu Nov  5 15:14:57 2009
----- Documentation for /scisoft/xop2.3/extensions/shadowvui/src/lib/retrace.pro -----

 NAME:
	RETRACE 
 PURPOSE:
	traces a SHADOW file a distance in vacuum
 CATEGORY:
	SHADOW's utilities.
 CALLING SEQUENCE:
	shadow_out = RETRACE(shadow_in,DISTANCE=distance)
 INPUTS:
	shadow_in   IDL structure with SHADOW data
 OPTIONAL INPUTS:
 KEYWORD PARAMETERS:
	DISTANCE  = distance the distance from the input position where
			data has to be evaluated
	RESERTY  = set this keyword to reset Y coordinates to zero
 OUTPUTS:
	a new IDL-SHADOW structure with the new data
 OPTIONAL OUTPUT PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 	None.
 RESTRICTIONS:
	None.
 PROCEDURE:
	Similar to SHADOW's RETRACE
 MODOFICATION HISTORY:
       93/08/02 MSR
	96/06/24 MSR fix a bug: before it was
	  {x,y,z} = {xo,yo,zo} + distance*{xprime,yprime,zprime}
	  and now:
	  {x,y,z} = {xo,yo,zo} + [(distance-yo)/yprime]*{xprime,yprime,zprime}
	  (both are approximately equivalent in the far field for 
	  mostly axial rays). 

	  For Info: SHADOW's retrace uses:
	  {x,y,z} = {xo,yo,zo} + [(distance)/yprime]*{xprime,yprime,zprime}
	  which is equivalent to the previous expression when analyzing
	  start and screen files, but it may differ when analyzing 
	  begin.dat files when the source has a depth.
	96/06/24 MSR added RESETY keyword
	06/09/18 Davide Bianchi + srio@esrf.fr fixed bug in the calculation

