#ifndef PS_REGION_H
#define PS_REGION_H

#include "psString.h"

/** Basic image region structure.
 *
 * Struct for specifying a rectangular area in an image.
 *
 */
typedef struct
{
    float x0;                         ///< the first column of the region.
    float x1;                         ///< the last column of the region.
    float y0;                         ///< the first row of the region.
    float y1;                         ///< the last row of the region.
}
psRegion;

/** Create a pointer to a psRegion, with associated psMemBlock.
 *
 * @return psRegion* : a new psRegion.
 */
psRegion *psRegionAlloc(float x0,       ///< the first column of the region.
                        float x1,       ///< the last column of the region + 1.
                        float y0,       ///< the first row of the region.
                        float y1        ///< the last row of the region + 1.
                       );

/** Create a psRegion with the specified attributes.
 *
 *  @return psRegion : a cooresponding psRegion.
 */
psRegion psRegionSet(
    float x0,                          ///< the first column of the region.
    float x1,                          ///< the last column of the region + 1.
    float y0,                          ///< the first row of the region.
    float y1                           ///< the last row of the region + 1.
);

/** Create a psRegion with the attribute values given as a string.
 *
 *  Create a psRegion with the attribute values given as a string.  The format
 *  shall be of the standard IRAF form '[x0:x1,y0:y1]'
 *
 *  @return psRegion:  A new psRegion struct, or NULL is not successful.
 */
psRegion psRegionFromString(
    const char* region                 ///< image rectangular region in the form '[x0:x1,y0:y1]'
);

/** Create a string of the standard IRAF form '[x0:x1,y0:y1]' from a psRegion.
 *
 *  @return psString:  A new string representing the psRegion as text, or NULL
 *                  is not successful.
 */
psString psRegionToString(
    const psRegion region              ///< the psRegion to convert to a string
);

/** Defines a region corresponding to the square with center at coordinate x,y
 *  and with coderadius.  The width of the square is 2radius + 1.
 *
 *  @return psRegion:       the newly defined psRegion.
 */
psRegion psRegionForSquare(
    double x,                           ///< x coordinate at square-center
    double y,                           ///< y coordinate at square-center
    double radius                       ///< radius of square
);


#endif
