/* Handling and I/O of imags with {float} samples. */
/* Last edited on 2017-06-29 18:36:10 by stolfilocal */

#ifndef dsm_image_H
#define dsm_image_H

#define _GNU_SOURCE
#include <stdio.h>

#include <bool.h>
#include <float_image.h>
#include <argparser.h>

#include <dsm_image_format.h>

/* IMAGE INPUT

  Each procedure in this section reads an image file in a specified
  format, including PNG, JPG, and PNM (PBM, PGM, PPM); and converts 
  it to a common format {float_image_t}, with sample values in the 
  range {[vlo_vhi]}.
    
  The file must not contain an alpha channel. It must be either RGB
  color (three samples per pixel) or grayscale (one sample per pixel).

  The decoding of the integer samples read from the file is defined by
  the parameters {gamma} and {vmax}. The range {R} of the resulting
  samples will be {[0 _ vmax]} if {vmax} is positive, or the symmetric
  interval {[-|vmax| _ +|vmax|]} if {vmax} is negative.
  
  If {gamma} is 1, the decoding is a simple affine mapping. Otherwise,
  the values are adjusted by a non-linear gamma mapping.
  
  Namely, the integer {p} read from the file, in the range {0..maxval},
  is first mapped to the number {s=(p+0.5)/(maxval+1)} in {[0_1]}. Then
  if (vmax} is negative, {s} is replaced by {2*s-1}, in {[-1 _ +1]}.
  Then the gamma correction is applied as described in
  {sample_conv_gamma_INFO}, with the given {gamma} and an internal
  default {bias}. Then finally the result is multiplied by {|vmax|}.
  
  If {gamma} is {NAN}, but the file specifies a gamma internally (or
  implicitly), the procedure uses the value from the file. (In that
  case,{vmax} had better be positive.) If {gamma} is {NAN} and the file
  does not have an internal or implicit gamma, these procedures use the
  default {gamma = 1.0}, i.e. no gamma decoding.

  If the {gray} parameter is true and the image is in color (three
  channels, RGB) it is converted to a single-channel grayscale image. */

#define dsm_image_size_MAX (float_image_max_size)
  /* Max expected image size along any axis. */

float_image_t *dsm_image_read
  ( const char *fname, 
    dsm_image_format_t ffmt, 
    double gamma,
    double vmax,
    bool_t gray
  );
  /* Reads an image from file {fname}, assumed to be in format {ffmt},
    and converts it to a float image.
    
    The file name extension must be included in {fname}, but does not
    affect the assumed file format. */

float_image_t *dsm_image_fread
  ( FILE *rd,
    dsm_image_format_t ffmt, 
    double gamma,
    double vmax,
    bool_t gray
  );
  /* Same as {dsm_image_read}, but reads from thefile handle {rd}
    instead of from a named file. The file {rd} must have been opened for reading,
    and is left open on return. */

float_image_t *dsm_image_read_frame
  ( const char *fpat, 
    int fnum, 
    dsm_image_format_t ffmt, 
    double gamma,
    double vmax,
    bool_t gray
  );
  /* Same as {dsm_image_read}, but the file name is obtained by
    substituting the frame number {fnum} for the "%..d" specification in
    {fpat}. The file name extension must be included in
    {fpat} but does not affect the assumed file format. */

/* IMAGE OUTPUT

  Each procedure in this section writes a {float_image_t} image to 
  an image files in the 16-bit-per-sample PNG format.
    
  The given image must have either 1 or 3 channels, and is assumed 
  to be grauscale or RGB color respectively. 

  The float samples are quantized so that they can be decoded with the
  decoding function defined by the {gamma} and {vmax} parameters,
  as described for the input routines.  In particular, if {gamma} is 1.0, the
  the encoding is a linear map from {[0 _ vmax]} or {[vmax _ -vmax}
  to {0..65535}. */

void dsm_image_write
  ( const char *fname, 
    float_image_t *fimg,
    double gamma,
    double vmax
  );
  /* Writes the float image {fimg} to a PNG image file called {fname}.  The 
    file name extension must be included in {fname}, but the file format
    will be PNG in any case. */

void dsm_image_fwrite
  ( FILE *wr, 
    float_image_t *fimg,
    double gamma,
    double vmax
  );
  /* Same as {dsm_image_write}, but writes to the file handle {wr}
    instead of to a named file. The file {wr} have been opened for writing,
    and is left open on return. */

void dsm_image_write_frame
  ( const char *fpat, 
    int fnum, 
    float_image_t *fimg,
    double gamma,
    double vmax
  );
  /* Same as {dsm_image_write}, but the file name is obtained by
    substituting the frame number {fnum} for the "%..d" specification in
    {fpat}. The file name extension must be included in {fpat}, but the
    file format will be PNG in any case. */


#endif