ncdf4a13/libsrc/nccoord.c

Go to the documentation of this file.

/*
This file is part of netcdf-4, a netCDF-like interface for HDF5, or a
HDF5 backend for netCDF, depending on your point of view.

This file handles the nc4 coordinate systems.

Copyright 2003, University Corporation for Atmospheric Research. See
netcdf-4/docs/COPYRIGHT file for copying and redistribution
conditions.

$Id: nccoord.c,v 2.6 2006/01/10 15:34:01 ed Exp $
*/

#include <netcdf.h>
#include <stdlib.h>
#include <string.h>

#define COORDINATE_AXIS_TYPE "_CoordinateAxisType"
#define COORDINATE_AXES "_CoordinateAxes"
#define COORDINATE_Z_IS_POSITIVE "_CoordinateZisPositive"
#define Z_UP "up"
#define Z_DOWN "down"
#define COORDINATE_SYSTEMS "_CoordinateSystems"
#define TRANSFORM_NAME "transform_name"
#define TRANSFORM_TYPE "_CoordinateTransformType"
#define COORDINATE_TRANSFORMS "_CoordinateTransforms"

static char* axis_type_name[] = {"", "Lat", "Lon", "GeoX", "GeoY", "GeoZ", 
                                 "Height", "Height", "Pressure", "Time", 
                                 "RadialAzimuth", "RadialElevation", 
                                 "RadialDistance"};

/* Here are functions for coordinate axis stuff. */
int
nc_def_axis_type(int ncid, int varid, int axis_type)
{
   int dimid;
   char var_name[NC_MAX_NAME + 1];
   int retval;

   /* Is the axis type valid? */
   if (axis_type < 0 || axis_type > NC_RADDIST)
      return NC_EINVAL;

   /* Make sure there's a dimension with the same name in this
    * ncid. */
   if ((retval = nc_inq_varname(ncid, varid, var_name)))
      return retval;
   if ((retval = nc_inq_dimid(ncid, var_name, &dimid)))
      return retval;

   /* Now write the attribute which stores the axis type. */
   if ((retval = nc_put_att_text(ncid, varid, COORDINATE_AXIS_TYPE, 
                                 strlen(axis_type_name[axis_type]) + 1, 
                                 axis_type_name[axis_type])))
      return retval;

   /* For height we write another attribute, indicating up
    * vs. down. */
   if (axis_type == NC_HEIGHT_UP)
   {
      if ((retval = nc_put_att_text(ncid, varid, COORDINATE_Z_IS_POSITIVE, 
                                    strlen(Z_UP) + 1, Z_UP)))
         return retval;
   }
   else if (axis_type == NC_HEIGHT_DOWN)
   {
      if ((retval = nc_put_att_text(ncid, varid, COORDINATE_Z_IS_POSITIVE, 
                                    strlen(Z_UP) + 1, Z_UP)))
         return retval;
   }

   return NC_NOERR;
}

int
nc_inq_axis_type(int ncid, int varid, int *axis_type)
{
   char value[NC_MAX_NAME + 1];
   int i;
   int retval;

   /* Get the attribute which stores the axis type. */
   if ((retval = nc_get_att_text(ncid, varid, COORDINATE_AXIS_TYPE, 
                                 value)))
      return retval;

   /* Which axis type is this? */
   for (i = 1; i <= NC_RADDIST; i++)
      if (!strcmp(value, axis_type_name[i]))
         break;

   /* For height we also have to look at another attribute to find out
    * whether it is up or down. At this point, i will equal
    * NC_HEIGHT_UP, find out whether it should be HEIGHT_DOWN. */
   if (i == NC_HEIGHT_UP)
   {
      if ((retval = nc_get_att_text(ncid, varid, COORDINATE_Z_IS_POSITIVE, 
                                    value)))
         return retval;
      if (!strcmp(value, Z_DOWN))
         i = NC_HEIGHT_DOWN;
   }

   /* Return a valid type if we found one, otherwise zero. */
   if (i > NC_RADDIST)
      return NC_NOAXISTYPE;
   
   if (axis_type)
      *axis_type = i;
   
   return NC_NOERR;
}


/* Define a coordinate system. This creates a var with contains a text
 * attribute, which is the names of the (coordinate) vars which make
 * up the axes of a coordinate system. */
int
nc_def_coord_system(int ncid, const char *name, int naxes, int *axis_varids, 
                    int *system_varid)
{
   int dimid, a;
   int varid;
   char var_name[NC_MAX_NAME + 1];
   char *coord_axes_str;
   int retval;
   
   /* naxes must be positive and less than max_dims. */
   if (naxes < 0)
      return NC_EINVAL;
   if (naxes > NC_MAX_DIMS)
      return NC_EMAXDIMS;

   /* Create a scalar var, type NC_CHAR, to hold the attribute that
    * defines this system. */
   if ((retval = nc_def_var(ncid, name, NC_CHAR, 0, NULL, &varid)))
      return retval;
   
   /* If the user wants it, return the varid of this system. */
   if (system_varid)
      *system_varid = varid;

   /* malloc space for the string which will hold the names of all the
    * axes. */
   if (!(coord_axes_str = malloc(naxes * NC_MAX_NAME + naxes)))
      return NC_NOERR;
   coord_axes_str[0] = 0;

   /* Store the names of the axes in an attribute. At the same time,
    * make sure that all the axis_varids are actually coordinate
    * variables - that is, there is a dimension withn the same
    * name. */
   for (a = 0; a < naxes; a++)
   {
      if ((retval = nc_inq_varname(ncid, axis_varids[a], var_name)))
         break;
      if ((retval = nc_inq_dimid(ncid, var_name, &dimid)))
         break;
      strcat(coord_axes_str, var_name);
      if (a < naxes - 1)
         strcat(coord_axes_str, " ");
   }
   
   /* If we arrived here without error, then write the coord_axes_str
    * to the appropriate attribute, to save the system in the file. */
   if (!retval)
      retval = nc_put_att_text(ncid, varid, COORDINATE_AXES, 
                               strlen(coord_axes_str) + 1, coord_axes_str);

   /* Free the memory we allocated. */
   free(coord_axes_str);
   
   return retval;
}

/* Inquire about a coordinate system. */
EXTERNL int
nc_inq_coord_system(int ncid, int system_varid, char *name, 
                    int *naxes, int *axis_varids)
{
   size_t len;
   int retval;
   char *coord_axes_str;
   char axis_name[NC_MAX_NAME + 1], system_name[NC_MAX_NAME + 1];
   int num_axes = 0, axes[NC_MAX_DIMS];
   char *p, *a;
   int a1;

   /* Get the name of this coordinate system, which is the same as the
    * name of this variable. */
   if ((retval = nc_inq_varname(ncid, system_varid, system_name)))
      return retval;

   /* If the caller wants the name, let them have it. */
   if (name)
      strcpy(name, system_name);

   /* Does the COORDINATE_AXES attribute exist. */
   if ((retval = nc_inq_att(ncid, system_varid, COORDINATE_AXES, 
                            NULL, &len)))
      return retval;

   /* Allocate space to read in the system string. */
   if (!(coord_axes_str = malloc(len)))
      return NC_NOERR;

   /* Read in the system string. */
   retval = nc_get_att_text(ncid, system_varid, COORDINATE_AXES, 
                            coord_axes_str);

   /* If we got the coord axes string, parse it to find the name's of
    * the coordinate vars which make up this system. */
   for (p = coord_axes_str; !retval && (p - coord_axes_str) < strlen(coord_axes_str);)
   {
      for (a = axis_name; *p && *p != ' '; )
         *a++ = *p++;
      p++;
      *a = '\0';
      
      retval = nc_inq_varid(ncid, axis_name, &axes[num_axes++]);
   }

   /* Thanks for the memories! */
   free(coord_axes_str);

   /* Give the user what they asked for. */
   if (naxes)
      *naxes = num_axes;
   if (axis_varids)
      for (a1 = 0; a1 < num_axes; a1++)
         axis_varids[a1] = axes[a1];
   
   return retval;
}

/* Given the varid of a system, write an attribute to a varid, whcih
 * indicates that it (the var) partakes of the system. Recall that the
 * system is just a collection of var names which are axes of the
 * coordinate system. */
int
nc_assign_coord_system(int ncid, int varid, int system_varid)
{
   char system_name[NC_MAX_NAME + 1];
   char *systems_str;
   size_t len, new_len = 0;
   int retval;

   /* Find the name of this system. */
   if ((retval = nc_inq_varname(ncid, system_varid, system_name)))
      return retval;

   /* Is the att already here? If so, get it's length, then it's
    * contents, then append a space and the new system name. */
   retval = nc_inq_att(ncid, varid, COORDINATE_SYSTEMS, NULL, &len);
   if (retval != NC_ENOTATT && retval != NC_NOERR)
      return retval;
   if (!retval)
      new_len += len;
   new_len += strlen(system_name) + 1;
   if (!(systems_str = malloc(new_len)))
      return NC_NOERR;
   systems_str[0] = 0;
   if (!retval)
   {
      if ((retval = nc_get_att_text(ncid, varid, COORDINATE_SYSTEMS, 
                                    systems_str)))
         return retval;
      strcat(systems_str, " ");
   }
   strcat(systems_str, system_name);

   /* Write an att, called _CoordinateSystems, which
    * contains a list of the system names related to this variable. */
   retval = nc_put_att_text(ncid, varid, COORDINATE_SYSTEMS, 
                            strlen(systems_str) + 1, systems_str);
      

   /* Free the memory we allocated. */
   free(systems_str);
   
   return retval;
}

/* Define a transform. This will create a scalar var of type NC_CHAR
 * to hold some attributes. */
int
nc_def_transform(int ncid, const char *name, const char *transform_type,
                 const char *transform_name, int *transform_varid)
{
   int varid;
   int retval;
   
   /* Create a scalar var, type NC_CHAR, to hold the attribute that
    * defines this transform. */
   if ((retval = nc_def_var(ncid, name, NC_CHAR, 0, NULL, &varid)))
      return retval;
   
   /* If the user wants it, return the varid of this system. */
   if (transform_varid)
      *transform_varid = varid;

   /* Store the transform_type, if provided by the user. */
   if (transform_type)
      if ((retval = nc_put_att_text(ncid, varid, TRANSFORM_TYPE, 
                                    strlen(transform_type) + 1, transform_type)))
         return retval;

   /* Store the transform name, if provided by the user. */
   if (transform_type)
      if ((retval = nc_put_att_text(ncid, varid, TRANSFORM_NAME, 
                                    strlen(transform_name) + 1, transform_name)))
         return retval;

   return NC_NOERR;
}

EXTERNL int
nc_inq_transform(int ncid, int transform_varid, char *name, size_t *type_len, 
                 char *transform_type, size_t *name_len, char *transform_name)
{
   int retval;

   /* Find the name of the transform var, if desired. */
   if (name)
      if ((retval = nc_inq_varname(ncid, transform_varid, name)))
         return retval;

   /* If the user wants the length of the transform_type, find it. */
   if (type_len)
      if ((retval = nc_inq_attlen(ncid, transform_varid, TRANSFORM_TYPE, 
                                  type_len)))
         return retval;

   /* If the user wants the transform type string, get it. */
   if (transform_type)
      if ((retval = nc_get_att_text(ncid, transform_varid, 
                                    TRANSFORM_TYPE, transform_type)))
         return retval;

   /* If the user wants the length of the transform_name, find it. */
   if (type_len)
      if ((retval = nc_inq_attlen(ncid, transform_varid, TRANSFORM_NAME, 
                                  name_len)))
         return retval;

   /* If the user wants the transform name string, get it. */
   if (transform_name)
      if ((retval = nc_get_att_text(ncid, transform_varid, 
                                   TRANSFORM_NAME, transform_name)))
         return retval;

   return NC_NOERR;
}

int
nc_assign_transform(int ncid, int system_varid, int transform_varid)
{
   char transform_name[NC_MAX_NAME + 1];
   int retval;

   /* Find the name of the transform. */
   if ((retval = nc_inq_varname(ncid, transform_varid, transform_name)))
      return retval;

   /* Write the transform name as an att of the system to which it
    * applies. */
   if ((retval = nc_put_att_text(ncid, system_varid, COORDINATE_TRANSFORMS, 
                                 strlen(transform_name) + 1, transform_name)))
      return retval;
   
   return NC_NOERR;
}

---