;+
; NAME:
;	vox_write
; PURPOSE:
;	Write a vox file for use with the Volume Pro board
; CATEGORY:
;	I/O
; CALLING SEQUENCE:
	PRO vox_write, Filename, Volume, $
		 _extra		=_extra		, $
		minf		= minf		, $
		maxf		= maxf		, $
		topb		= topb		, $
		volumename	= VolumeName, $
		copyright	= Copyright	, $
		general_comments= General_Comments,	$
		volume_comments	= Volume_Comments , $
		silent		= silent
; INPUTS:
;	Filename	scalar; type: string
;				file name for vox file
;	Volume		array[N,N,N]; type: any
;				array to be written to vox file
;				If the array is not of type byte it will be
;				converted to byte using the IDL bytscl function.
; OPTIONAL INPUT PARAMETERS:
;	minf=minf	passed to IDL function bytscl in min keyword
;	maxf=maxf	passed to IDL function bytscl in max keyword
;	topb=topb	passed to IDL function bytscl in top keyword
;
;	ndim=ndim	scalar; type: integer
;				resolution of the binary file stored in the vox file
;				if specified then the IDL function congrid is used to
;				rebin the array to ndim in all three dimensions
;	volumename = VolumeName
;				scalar; type: string; default: 'Data'
;				identifying name of volume data
;	copyright = Copyright
;				scalar; type: string; default: 'UCSD/CASS Solar Physics Group'
;				copyright notice
;	general_comments	= General_Comments
;				array; type: string
;				comments stored as part of the general header information
;	volume_comments		= Volume_Comments
;				array; type: string
;				comments stored as part of the volume section describing the
;				data array V.
;	silent=silent
;				scalar; type: integer
;				1 or 2: suppress informational messages (higher value suppresses
;				more information)
; OUTPUTS:
;	(vox file)
; INCLUDE:
	@compile_opt.pro				; On error, return to caller
; CALLS:
;	InitVar, IsType, boost
; RESTRICTIONS:
; PROCEDURE:
;	The vox file format is described in the pdf document
;	vp500_vol_file_format.pdf (RTViz Voxel File Format) available at
;		http://www.terarecon.com/support/vp500/vp500_sup_document.html
;	(link was alive as of 2003/05/28)
;
;	The main sections are a header section for general information, followed
;	by sections for each of the data volumes (including the data array
;	itself). Currently only a single volume is stored.
;
;	The 'Endian' indicator is set to 'B'. Note that Intel/AMD processors
;	are actually little endian. Since endian-ness only affects byte ordering
;	the setting doesn't matter as long as byte data are written to the vox
;	file.
; MODIFICATION HISTORY:
;	JAN-2001, Paul Hick (UCSD/CASS)
;	JUL-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;		Added /silent keyword
;-
InitVar, silent, 0

IF IsType(Filename,/undefined) or IsType(Volume,/undefined) THEN	$
	message, 'usage: WRITE_VOX, file, volume'


InitVar, VolumeName, 'Data'
InitVar, Copyright , 'UCSD/CASS Solar Physics Group'

byte_volume = IsType(Volume, /byte_x)

CASE byte_volume OF
0: BEGIN
	F = bytscl(Volume, /nan, min=minf, max=maxf, top=topb)	; Convert to byte

	IF IsType(minf,/defined) THEN fmin = minf ELSE fmin = min(Volume, /nan)
	IF IsType(maxf,/defined) THEN fmax = maxf ELSE fmax = max(Volume, /nan)
	IF IsType(topb,/defined) THEN btop = topb ELSE btop = 255

	boost, Volume_Comments, ['min'+strcompress(fmin), 'max'+strcompress(fmax), 'top'+strcompress(btop) ]
END
1: F = Volume
ENDCASE

sz = size(F, /dim)
IF IsType(ndim,/defined) THEN BEGIN
	IF sz[0] NE ndim OR sz[1] NE ndim OR sz[2] NE ndim THEN BEGIN
		F = congrid(F, ndim, ndim, ndim)
	    sz = size(F, /dim)
	ENDIF
ENDIF

VolumeSize = strjoin(strcompress(sz))

sz = IsType(F, bytes=VoxelSize)
VoxelSize	= strcompress(8*VoxelSize)
Field		= 'Position 0 Size'+VoxelSize+' Name '+VolumeName

NL = string('0a'XB)
FF = string('0c'XB)

IF silent LE 0 THEN BEGIN

	print

	message, /info, 'General Comments:'
	FOR i=0,n_elements(General_Comments)-1 DO message, /info, General_Comments[i]

	print

	message, /info, 'Volume Comments:'
	FOR i=0,n_elements(Volume_Comments )-1 DO message, /info, Volume_Comments[i]

	print

ENDIF

header =	[ $
	'Vox1999a',					$		; Begin of header
	'VolumeCount 1',			$
	'//'+General_Comments,		$
	'Copyright '+Copyright,		$
	'##'+ FF,					$		; End of header

	'##',						$		; Begin of volume
	'VolumeSize'+VolumeSize,	$
	'VoxelSize '+VoxelSize,		$
	'Endian B',					$
	'Field 0 ('+Field+')',		$

	'//'+Volume_Comments,		$

	'##'+ FF ]							; End of volume


IF silent LE 1 THEN message, /info, Filename



on_ioerror, cleanup

openw, /get_lun, iu, FileName

writeu, iu,	strjoin(header,NL)+NL, F

free_lun, iu


on_ioerror, NULL

RETURN


cleanup:

IF IsType(iu, /defined) THEN free_lun, iu

on_ioerror, NULL

message, strmessage( !error_state.code )

RETURN  &  END