FUNCTION Scl, x, res=res, help=help
;+
; NAME:
;
;   SCL
;
; PURPOSE:
;
;   Convert image pixel units into device pixel coordinates so that
;   screen and printer pixels have the save size. This makes it easier
;   for image display that is independent of whether device is the
;   screen or a device with scalable pixels (e.g., a postscript
;   printer). Use this routine with XYOUTS or when scaling a plot and
;   you want to use pixel units for positions and sizes.
;
; CATEGORY:
;
;   Image Display
;
; CALLING SEQUENCE:
;
;   Result = SCL(X)
; 
; INPUTS:
;
;   X - Array of values in pixel units. 
;
; KEYWORD PARAMETERS:
;
;   RES - resolution in dots per inch - this only affects printing to
;         postscript. A dot is the same thing as an image pixel.
;         Defaults to 75.0 for a postscript device; otherwise, it is
;         fixed for the screen (around 75-100 dpi).
;
;   HELP - Provide help (this information). No other action is performed.
;
; OUTPUTS:
;
;   Result - The X data scaled from pixel units into device units
;            where the size of a pixel is given by RES. For fixed size
;            pixel devices (typically screen devices) Result = X.
;
; RESTRICTIONS:
;
;  Assumes the device pixel size is square. Thus, displays using SCL
;  may give unexpected results if the device y pixel size (!D.y_px_cm)
;  is not the same as the device x pixel (!D.x_px_cm).
;  
; PROCEDURE:
;
;   Determines if the current device has scalable pixels. If so, gets
;   the size of the pixels (assumed square) and scales the data
;   according to the resolution (RES).
;
; EXAMPLE:
;
;   ; In this example I use SCL everywhere that I need a size or
;   ; position in terms pixels.
;   image = SIN(DIST(200,200)*(4*!pi/200.))
;
;   ; Display the image offset by 50 pixels      
;   TVSCL,image,SCL(50),SCL(50),XSIZE=SCL(200),YSIZE=SCL(200),/DEVICE
;
;   ; Position a centered label, 5 pixels above the image   
;   XYOUTS,SCL(150),SCL(255),'This is a label',ALIGN=.5,/DEVICE
;   
;   ; Or using the MTV routine to do the same thing alongside the first.
;   ; MTV does not require scaling the image position.
;   MTV,image,250,50
;   
;   ; Position a centered label, 5 pixels above the image   
;   XYOUTS,SCL(350),SCL(255),'Another label',align=.5,/DEVICE
;
;   ; Overlay first image with a contour.
;   CONTOUR,image,POSITION=SCL(50+[0,0,200,200]),XSTYLE=1,YSTYLE=1, $
;           /NOERASE,/DEVICE
;           
;   ; This will produce the same results whether the device is for the
;   ; screen or a postscript printer.
;
; MODIFICATION HISTORY:
;
;       Mon Mar 22 15:50:47 1993, Chris Chase <chase@johnston>
;               Created.   
;
;-

IF KEYWORD_SET(help) THEN BEGIN
   doc_library, 'scl
   RETURN,0 
ENDIF
   
;
; Use a default pixel size of 75 dots per inch for scalable device pixels.
; Otherwise, for fixed size device pixels use the actual size
; 
IF NOT KEYWORD_SET(res) THEN res = 75.0 $
  ELSE res = float(res)

;; check for scalable pixels.
;; scl has units of device pixels per image pixel (dots).
IF (!D.flags AND 1) THEN BEGIN
   scl = 2.54*!D.x_px_cm/res    ; 2.54 cm/inch
   RETURN,(x*scl)
ENDIF
RETURN, x
END