\chapter{Image API Reference}
\label{ch:imageapi}

\section{Image Definitions}

\subsection{Image Formats}
\label{subsec:imageformats}

Each image handled by MX has a defined image format.  The following
three formats are the most important ones:
%
\begin{description}
  \item[MXT\_IMAGE\_FORMAT\_RGB (1)]\ \newline
  	This is a 24-bit color format with 8 bits each
	for Red, Green, and Blue.
  \item[MXT\_IMAGE\_FORMAT\_GREY8 (2)]\ \newline
  	This format is 8-bit greyscale.
  \item[MXT\_IMAGE\_FORMAT\_GREY16 (3)]\ \newline
  	This format is 8-bit greyscale.
\end{description}
%
These formats are important since all other in memory image formats are
eventually converted to one of these three format by MX.
Keep in mind that in memory image formats are not the same
as datafile image formats.

The following formats are raw formats as generated by image capture boards:
\begin{description}
  \item[MXT\_IMAGE\_FORMAT\_RGB565]\ \newline
  	This is a 16-bit color format with 5 bits for red, 6 bits for green,
	and 5 bits for blue.
  \item[MXT\_IMAGE\_FORMAT\_YUYV]\ \newline
  	This is a packed YCbCr color format which is known in
	the Windows world as YUY2.
\end{description}

\subsection{Datafile Formats}
\label{subsec:datafileformats}

Two file formats are currently supported.  They are:
\begin{description}
  \item[MXT\_IMAGE\_FILE\_PNM]\ \newline
  	The PNM file format is described at
	( \mxurl{http://netpbm.sourceforge.net/doc/index.html} ).
	It is supported by a wide variety of image viewing
	programs in the Linux/Unix world and is supported at least
	by Irfanview in the Windows world.  This format
	is not intended for routine use with scientific data, since it
	does not really have a place to store header information.
  %
  \item[MXT\_IMAGE\_FILE\_SMV]\ \newline
  	The SMV file format is used for area detectors from
	companies like
	AVIEX ( \mxurl{http://www.aviex-tech.com/} ) and
	ADSC ( \mxurl{http://www.adsc-xray.com/} ).
	This format is widely supported by scientific analysis software
	in the crystallography, diffraction, and scattering communities.
\end{description}

\subsection{Image Headers}
\label{subsec:imageheaders}

MX\_IMAGE\_FRAME structures contain a binary image header in the
\textit{header\_data} element of the structure.  This binary header
is \textit{not} intended to be written to disk, since the last thing
the world needs is yet another image file format.  However,
\textit{header\_data} serves as a convenient place in which to store values
that are read from or written to disk files and detectors.  Values in
the binary image header are always 32-bit integers in native byte order.

There are number of macros that can be used to get and set the values
of header variables.  Here is a list of the current header variables
with \textit{image\_frame} standing for a pointer to an MX\_IMAGE\_FRAME
structure:
\begin{description}
  \item[MXIF\_HEADER\_BYTES( \textmd{\it image\_frame} )]\ \newline
  	This contains the length of \textit{header\_data} in bytes.
	In general, it is a bad idea to write to this value.
  \item[MXIF\_ROW\_FRAMESIZE]( \textmd{\it image\_frame} )\ \newline
        This is the width of the image in pixels.
  \item[MXIF\_COLUMN\_FRAMESIZE]( \textmd{\it image\_frame} )\ \newline
  	This is the height of the image in pixels.
  \item[MXIF\_ROW\_BINSIZE( \textmd{\it image\_frame} )]\ \newline
  	This value describe how many raw detector pixels were combined
	in the horizontal direction to create one image pixel.
  \item[MXIF\_COLUMN\_BINSIZE( \textmd{\it image\_frame} )]\ \newline
  	This value describe how many raw detector pixels were combined
	in the vertical direction to create one image pixel.
  \item[MXIF\_IMAGE\_FORMAT( \textmd{\it image\_frame} )]\ \newline
  	The supported image format types are described in
		Section~\ref{subsec:imageformats}.
  \item[MXIF\_BYTE\_ORDER( \textmd{\it image\_frame} )]\ \newline
  	0x1 = Big-endian, 0x2 = Little-endian.
  \item[MXIF\_BYTES\_PER\_MILLION\_PIXELS( \textmd{\it image\_frame} )]
  \ \newline
        Some existing image formats have a non-integer number of bytes
	per pixel.  We handle this by multiplying that non-integer
	value by $10^6$ and then rounding that to the nearest integer.
  \item[MXIF\_BITS\_PER\_PIXEL( \textmd{\it image\_frame} ) ]\ \newline
  	The number of significant bits of data per pixel.
  \item[MXIF\_EXPOSURE\_TIME\_SEC( \textmd{\it image\_frame} )]
  \item[MXIF\_EXPOSURE\_TIME\_NSEC( \textmd{\it image\_frame} )]\kern-8pt \ \newline
  	These variables contain the exposure time in seconds.
	The integer part goes in MXIF\_EXPOSURE\_TIME\_SEC() while
	the fractional remainder is placed in MXIF\_EXPOSURE\_TIME\_NSEC()
	expressed in units of nanoseconds.\newline
  \item[MXIF\_TIMESTAMP\_SEC( \textmd{\it image\_frame} )]
  \item[MXIF\_TIMESTAMP\_NSEC( \textmd{\it image\_frame} )]\kern-8pt\ \newline
  	These variables contain the time at which the image frame was
	acquired using the same format as the exposure time.
	The times are expressed relative to the Posix Epoch of 
	(00:00:00 UTC, January 1, 1970).
\end{description}
%
All of these macros are defined in such a way that they can be assigned to.
In esoteric terms, they expand to expressions that are C language l-values;
For example, the following is valid code to set the exposure time
to 2.5 seconds:
\begin{verbatim}
        MXIF_EXPOSURE_TIME_SEC(image_frame)  = 2;
        MXIF_EXPOSURE_TIME_NSEC(image_frame) = 500000000;
\end{verbatim}

There are a couple of additional macros that convert the
MXIF\_BYTES\_PER\_MILLION\_PIXELS to and from double precision
\textit{bytes per pixel} values.  The first macro is
%
\begin{description}
  \item[{\hskip 8mm}MXIF\_BYTES\_PER\_PIXEL( \textmd{\it image\_frame} )]
\end{description}
%
which returns the number of bytes per pixel as a double.
This macro expands to a C expression that is \textit{not} an l-value,
so we have to have the following macro as well:
%
\begin{description}
  \item[{\hskip 8mm}MXIF\_SET\_BYTES\_PER\_PIXEL( \textmd{\it image\_frame, bytes\_per\_pixel} )]
\end{description}
%

\section{mx\_image\_alloc}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_alloc} - allocate an MX\_IMAGE\_FRAME object
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_alloc}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_IMAGE\_FRAME **frame, \\
				long row\_framesize, \\
				long column\_framesize, \\
				long image\_format, \\
				long byte\_order, \\
				double bytes\_per\_pixel, \\
				size\_t header\_length, \\
				size\_t image\_length );
			\end{tabular}
%
  \mxdescription
    The \mxfn{mx\_image\_alloc()}
    function either creates a new MX\_IMAGE\_FRAME object or else
    changes the size of an existing MX\_IMAGE\_FRAME object to match
    the supplied function arguments.  If you want to automatically fetch
    the appropriate settings from your area detector record,
    you should use \mxfn{mx\_area\_detector\_setup\_frame()} instead.

    This function takes as its first argument a pointer to an
    MX\_IMAGE\_FRAME pointer.  If the frame pointer passed is NULL,
    as in this example
\begin{verbatim}
        ...
        MX_IMAGE_FRAME *frame;
        ...
        frame = NULL;
        ...
        mx_status = mx_image_alloc( &frame, ... );
        ...
\end{verbatim}
    then \mxfn{mx\_image\_alloc()} will create a new MX\_IMAGE\_FRAME
    structure using the requested configuration.

    If the frame pointer passed to \mxfn{mx\_image\_alloc()}
    is \textit{not} NULL, \mxfn{mx\_image\_alloc()} will examine the
    current configuration of the supplied MX\_IMAGE\_FRAME structure
    to see if it is already capable of holding an image frame with
    the requested configuration.  If the object can already hold the frame,
    \mxfn{mx\_image\_alloc()} returns without doing anything else.
    If the object \textit{cannot} already hold the image frame,
    \mxfn{mx\_image\_alloc()} will resize the \textit{image\_data}
    and \textit{header\_data} arrays in the object so that they are
    big enough to hold an image frame with the new dimensions.  If the
    image frame object is resized, the old contents of the 
    \textit{image\_data} and \textit{header\_data} arrays are
    not preserved.

    The arguments for \mxfn{mx\_image\_alloc()} as follows:

    \begin{description}
      \item \textit{MX\_IMAGE\_FRAME **frame}\newline
      	A pointer to the MX\_IMAGE\_FRAME object as described above.
%
      \item \textit{long row\_framesize}\newline
        This argument contains the width of the image in pixels.
%
      \item \textit{long column\_framesize}\newline
        This argument contains the height of the image in pixels.
%
      \item \textit{long image\_format}\newline
        This argument specifies the greyscale or color format of the image data.
        The currently supported values for the image format
	are described in Section~\ref{subsec:imageformats}.
%
      \item \textit{long byte\_order}\newline
        This is set to 0x1 if the image data is in big endian format
	or to 0x2 if the image data is in little endian format.
%
      \item \textit{double bytes\_per\_pixel}\newline
        The number of bytes that corresponds to one pixel.  There exist
	some image formats for which this quantity is not an integer,
	so we specify it here as a \textit{double}.
%
      \item \textit{size\_t header\_length}\newline
        The length of the image header in bytes.  If this length
	is specified as 0, then no memory will be allocated
	for an image header.
%
      \item \textit{size\_t image\_length}\newline
        The length of the image data array in bytes.  This length
	must be greater than 0.
    \end{description}
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_setup\_frame()},
    \mxfn{mx\_image\_free()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_copy\_1d\_pixel\_array}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_copy\_1d\_pixel\_array}
    	- copies the image data array to an application program buffer
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_copy\_1d\_pixel\_array}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_IMAGE\_FRAME *frame, \\
				void *destination\_pixel\_array, \\
				size\_t max\_array\_bytes, \\
				size\_t *num\_bytes\_copied ); \\
			\end{tabular}
%
  \mxdescription
    This function copies the contents of the \textit{image\_data} array
    to an application program supplied buffer.  No more than
    \textit{max\_array\_bytes} will be copied to the buffer.
    On return, the \textit{num\_bytes\_copied} pointer will point to the
    the number of bytes actually copied to the destination array.  This
    number can be smaller than the requested number of bytes if the actual
    length of the \textit{image\_data} array is shorter than the value
    of \textit{max\_array\_bytes}.  If you do not need to know the
    number of bytes copied, you can set the last argument of the
    function to a NULL pointer.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_image\_get\_image\_data\_pointer()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_copy\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_copy\_frame}
    	- copies the contents of one MX\_IMAGE\_FRAME object to another
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_copy\_frame}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_IMAGE\_FRAME *old\_frame, \\
				MX\_IMAGE\_FRAME **new\_frame); \\
			\end{tabular}
%
  \mxdescription
    This function copies the contents of the existing \textit{old\_frame}
    object to the \textit{new\_frame} object, which may or may not
    already exist.  This function uses \mxfn{mx\_image\_alloc()} internally,
    so if \textit{new\_frame} does not already exist, it will be created,
    while if \textit{new\_frame} does already exist, it will be enlarged
    to contain the copy, if necessary.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_image\_alloc()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_copy\_header}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_copy\_frame}
    	- copies the header of one MX\_IMAGE\_FRAME
		to another MX\_IMAGE\_FRAME
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_copy\_header}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_IMAGE\_FRAME *source\_frame, \\
				MX\_IMAGE\_FRAME *destination\_frame); \\
			\end{tabular}
%
  \mxdescription
    This function copies the header from \textit{source\_frame}
    to \textit{destination\_frame}.  This is mostly an infrastructure
    function, so application programs will probably never call it.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_image\_copy\_frame()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_free}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_free}
    	- frees an MX\_IMAGE\_FRAME structure.
%
  \mxsynopsis
    void \mxfn{mx\_image\_free}\ ( MX\_IMAGE\_FRAME *frame );
%
  \mxdescription
    This function frees all of the data structures allocated for
    the specified MX\_IMAGE\_FRAME object.  The object must not be
    used after this function has been invoked.
%
  \mxreturnvalue
    \mxfn{mx\_image\_free} does not return a value, since the \mxfn{free()}
    function invoked by it does not return a value either.
%
  \mxseealso{
    \mxfn{mx\_image\_alloc()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_get\_average\_intensity}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_get\_average\_intensity}
    	- reports the average intensity of an MX\_IMAGE\_FRAME
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_get\_average\_intensity}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_IMAGE\_FRAME *frame, \\
				double *average\_intensity ); \\
			\end{tabular}
%
  \mxdescription
    This function returns the average intensity for the image data in 
    the specified MX\_IMAGE\_FRAME object.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_get\_exposure\_time}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_get\_exposure\_time}
    	- reports the exposure time of an MX\_IMAGE\_FRAME
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_get\_exposure\_time}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_IMAGE\_FRAME *frame, \\
				double *exposure\_time ); \\
			\end{tabular}
%
  \mxdescription
    This function returns the recorded exposure time in seconds for
    the specified MX\_IMAGE\_FRAME object.  If the header of the frame
    does not contain the exposure time or the frame was read from a
    file format that does not store the exposure time,
    the exposure time will be reported as 1 second.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_get\_format\_name\_from\_type}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_get\_format\_name\_from\_type}
    	- converts a numerical image format type to a text representation
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_get\_format\_name\_from\_type}\ (
    			\begin{tabular}[t]{@{}l}
				long type, \\
				char *name, \\
				size\_t max\_name\_length ); \\
			\end{tabular}
%
  \mxdescription
    This function takes a numerical image format type as defined near
    the top of the \textbf{\$MXDIR/include/mx\_image.h} header file
    and converts it into a matching text representation.  The function
    will only copy up to \textit{max\_name\_length} bytes to
    the \textit{name} buffer.  The text representation returned
    will be in upper case.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_image\_get\_format\_type\_from\_name()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_get\_format\_type\_from\_name}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_get\_format\_name\_from\_type}
    	- converts the name of an image format type to a numerical value
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_get\_format\_type\_from\_name}\ (
    			\begin{tabular}[t]{@{}l}
				char *name, \\
				long type ); \\
			\end{tabular}
%
  \mxdescription
    This function takes the text representation of an image format
    and converts it to a numerical image format type as defined near
    the top of the \textbf{\$MXDIR/include/mx\_image.h} header file.
    The text representation can be in either upper or lower case.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_image\_get\_format\_name\_from\_type()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_get\_frame\_from\_sequence}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_get\_frame\_from\_sequence}
    	- returns the requested frame from an MX\_IMAGE\_SEQUENCE object
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_get\_frame\_from\_sequence}\ (
	    			\begin{tabular}[t]{@{}l}
					MX\_IMAGE\_SEQUENCE *sequence, \\
					long frame\_number, \\
					MX\_IMAGE\_FRAME **image\_frame ); \\
				\end{tabular}
%
  \mxdescription
    This function returns the MX\_IMAGE\_FRAME object corresponding to
    the requested \textit{frame\_number} from the specified
    MX\_IMAGE\_SEQUENCE object.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_get\_image\_data\_pointer}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_get\_image\_data\_pointer}
    	- returns a pointer to the image data for an
	MX\_IMAGE\_FRAME object
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_get\_image\_data\_pointer}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_IMAGE\_FRAME *frame, \\
				size\_t *image\_length, \\
				void **image\_data\_pointer ); \\
			\end{tabular}
%
  \mxdescription
    This function returns the length of the image and 
    the image data pointer for the specified MX\_IMAGE\_FRAME object.
    You must know the image format, which can be found at
    \textit{frame->image\_format}, in order to successfully manipulate
    the image data.  However, for most area detectors this value will
    always be the same.
    
    As an example, the AVIEX PCCD-170170 CCD detector always uses a
    \textit{GREY16} image format, which means
    that the image data made up of 16-bit greyscale pixels.  MX already
    has a C99-compatible \textit{uint16\_t} typedef in the
    \mxfn{\$MXDIR/include/mx\_stdint.h} header file which can be used
    to manipulate this data format.
%
  \mxwarning
    If an MX imaging function increases the size of the \textit{image\_data}
    array in an MX\_IMAGE\_FRAME structure, the old \textit{image\_data}
    array will be freed and a new one allocated in its place.  In general,
    the new \textit{image\_data} array will be at a different address,
    which means that an \textit{image\_data\_pointer} returned by a
    previous call to \mxfn{mx\_image\_get\_image\_data\_pointer()}\ 
    will no longer be valid.  In general, the safest thing to do is
    to reinvoke \mxfn{mx\_image\_get\_image\_data\_pointer()} each time
    that you need this pointer.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_image\_copy\_1d\_pixel\_array()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_read\_file}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_read\_file}
    	- reads an image frame from a disk file into an MX\_IMAGE\_FRAME object
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_read\_file}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_IMAGE\_FRAME **frame, \\
				unsigned long datafile\_type, \\
				char *datafile\_name ); \\
			\end{tabular}
%
  \mxdescription
    This function reads an image frame from the disk file specified by
    the \textit{datafile\_name} argument on the user application computer
    into the specified MX\_IMAGE\_FRAME.  If needed, the MX\_IMAGE\_FRAME
    object will be created or resized internally by \mxfn{mx\_image\_alloc()}.

    If you want to read an image on the detector computer's disk into
    one of the frame buffers of the detector computer's server, you should
    be using \mxfn{mx\_area\_detector\_load\_frame()} instead.
%
  \mxwarning
    The \textit{datafile\_type} supplied must match the actual data format
    of the disk file or else \mxfn{mx\_image\_read\_file()} will fail
    with an error.  \mxfn{mx\_image\_read\_file()} does not attempt to
    detect the file format on its own.
    See Section~\ref{subsec:datafileformats}
    for the list of supported datafile formats.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_load\_frame()},
    \mxfn{mx\_image\_write\_file()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_rebin}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_rebin}
    	- creates a rebinned image frame from another image frame
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_rebin}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_IMAGE\_FRAME **rebinned\_frame, \\
				MX\_IMAGE\_FRAME *original\_frame, \\
				unsigned long row\_rebinning\_factor, \\
				unsigned long column\_rebinning\_factor ); \\
			\end{tabular}
%
  \mxdescription
    This function reads an existing original image frame and creates a
    new rebinned version.  The rebinning process replaces rectangular groups
    of pixels with a single pixel that contains the average of the pixel
    values in the original rectangular group.  For example, suppose you
    write something like this:
\begin{verbatim}
...
mx_status = mx_image_rebin( &rebinned_frame, original_frame, 4, 2 );
...
\end{verbatim}
    where \textit{original\_frame} is a 4096x4096 image frame.  The
    rebinned frame will be a 1024x2048 pixel image frame.  Each
    pixels in the rebinned frame then corresponds to the average
    of a group of pixels in the original frame that is 4 columns
    wide and 2 rows high.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
%  \mxseealso{
%  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_image\_write\_file}
%
\begin{description}
  \mxname
    \mxfn{mx\_image\_write\_file}
    	- writes the contents of an MX\_IMAGE\_FRAME object to a disk file
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_image\_write\_file}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_IMAGE\_FRAME **frame, \\
				unsigned long datafile\_type, \\
				char *datafile\_name ); \\
			\end{tabular}
%
  \mxdescription
    This function writes the contents of an MX\_IMAGE\_FRAME to the disk file
    specified by the \textit{datafile\_name} argument on the
    user application computer.  You must specify the file format
    you want in the \textit{datafile\_type} argument.
    See Section~\ref{subsec:datafileformats}
    for the list of supported datafile formats.

    If you want to write an image buffer in the detector computer's server
    to a file on the detector computer's disk, you should
    be using \mxfn{mx\_area\_detector\_save\_frame()} instead.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_save\_frame()},
    \mxfn{mx\_image\_read\_file()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_sequence\_get\_exposure\_time}
%
\begin{description}
  \mxname
    \mxfn{mx\_sequence\_get\_exposure\_time}
    	- returns the exposure time for the specified frame in a sequence
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_sequence\_get\_exposure\_time}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_SEQUENCE\_PARAMETERS *sp, \\
				long frame\_number, \\
				double *exposure\_time ); \\
			\end{tabular}
%
  \mxdescription
    This function returns the exposure time in seconds
    for the specified frame number
    in a sequence.  For most sequences, the exposure time is the same
    for all frames.  However, for Geometrical and Subimage sequences,
    each frame can have a different exposure time.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_sequence\_get\_average\_intensity()},
    \mxfn{mx\_sequence\_get\_frame\_time()},
    \mxfn{mx\_sequence\_get\_num\_frames()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_sequence\_get\_frame\_time}
%
\begin{description}
  \mxname
    \mxfn{mx\_sequence\_get\_frame\_time}
    	- returns the duration of the specified frame in a sequence
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_sequence\_get\_frame\_time}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_SEQUENCE\_PARAMETERS *sp, \\
				long frame\_number, \\
				double *exposure\_time ); \\
			\end{tabular}
%
  \mxdescription
    This function returns the frame duration in seconds
    for the specified frame number
    in a sequence.  For most sequences, the frame duration is the same
    for all frames.  However, for Geometrical and Subimage sequences,
    each frame can have a different frame duration.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_sequence\_get\_exposure\_time()},
    \mxfn{mx\_sequence\_get\_num\_frames()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_sequence\_get\_num\_frames}
%
\begin{description}
  \mxname
    \mxfn{mx\_sequence\_get\_num\_frames}
    	- returns the total number of frames in a sequence
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_sequence\_get\_num\_frames}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_SEQUENCE\_PARAMETERS *sp, \\
				long *num\_frames ); \\
			\end{tabular}
%
  \mxdescription
    This function returns the total number of frames in a sequence.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_sequence\_get\_exposure\_time()},
    \mxfn{mx\_sequence\_get\_frame\_time()}
  }

\end{description}

