clusterlib doc doxygenized

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@38544 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/cluster/c_assign.c

@@ -1,6 +1,28 @@
+/*!
+  \file cluster/c_assign.c
+  
+  \brief Cluster library - Assign cluster
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <math.h>
 #include <grass/cluster.h>
 
+/*!
+  \brief Assign cluster
+
+  \param C pointer to Cluster structure
+  \param interrupted ?
+  
+  \return -1 on interrupted
+  \return 0 on success
+*/
 int I_cluster_assign(struct Cluster *C, int *interrupted)
 {
     int p, c;
@@ -8,11 +30,9 @@ int I_cluster_assign(struct Cluster *C, int *interrupted)
     double d, q;
     double dmin;
 
-    /*
-       fprintf (stderr,"I_cluster_assign(npoints=%d,nclasses=%d,nbands=%d)\n",
-       C->npoints, C->nclasses, C->nbands);
-     */
-
+    G_debug("I_cluster_assign(npoints=%d,nclasses=%d,nbands=%d)",
+	    C->npoints, C->nclasses, C->nbands);
+    
     for (p = 0; p < C->npoints; p++) {
 	if (*interrupted)
 	    return -1;

lib/cluster/c_begin.c

@@ -1,18 +1,30 @@
+/*!
+  \file cluster/c_begin.c
+  
+  \brief Cluster library - Begin clusterring
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <stdlib.h>
+#include <grass/glocale.h>
 #include <grass/cluster.h>
 
-/****************************************************************
- * I_cluster_begin (C,nbands)
- *
- * initialize the cluster routines for nbands
- *
- * returns 
- *  0 ok
- * -1 out of memory
- *  1 illegal number of bands
- *
- ***************************************************************/
+/*!
+  \brief Initialize the cluster routines for nbands
+
+  \param C pointer to Cluster structure
+  \param nbands number of bands
 
+  \return 0 ok
+  \return -1 out of memory
+  \return 1 illegal number of bands
+*/
 int I_cluster_begin(struct Cluster *C, int nbands)
 {
     int band;
@@ -42,7 +54,7 @@ int I_cluster_begin(struct Cluster *C, int nbands)
     /* prepare the signatures for nbands */
 
     I_init_signatures(&C->S, nbands);
-    sprintf(C->S.title, "produced by i.cluster");
+    sprintf(C->S.title, _("produced by i.cluster"));
 
     /* allocate the data (points) arrays */
     C->points = (DCELL **) malloc(C->nbands * sizeof(DCELL *));

lib/cluster/c_clear.c

@@ -1,4 +1,25 @@
+/*!
+  \file cluster/c_clear.c
+  
+  \brief Cluster library - Clear structures
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <grass/cluster.h>
+
+/*!
+  \brief Clear Cluster structure
+
+  \param C pointer to Cluster structure
+
+  \return 0
+*/
 int I_cluster_clear(struct Cluster *C)
 {
     C->points = NULL;

lib/cluster/c_distinct.c

@@ -1,5 +1,26 @@
+/*!
+  \file cluster/c_distinct.c
+  
+  \brief Cluster library - Distinct value
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <grass/cluster.h>
 
+/*!
+  \brief Get distinct value
+
+  \param pointer to Cluster structure
+  \param separation separation value
+
+  \return distiction value
+*/
 int I_cluster_distinct(struct Cluster *C, double separation)
 {
     int class1, class2;

lib/cluster/c_exec.c

@@ -1,25 +1,31 @@
+/*!
+  \file cluster/c_exec.c
+  
+  \brief Cluster library - Exectute clusterring
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
 
-/***************************************************************
- *
- * I_cluster_exec (C, maxclass, iterations,
- *               convergence, separation, min_class_size,
- *               checkpoint, interrupted)
- *
- *  maxclass       maximum number of classes
- *  iterations     maximum number of iterations
- *  convergence    percentage of points stable
- *  separation     minimum distance between class centroids
- *  checkpoint     routine to be called at various steps
- *  interrupted    boolean to check for interrupt
- *
- * returns:
- *   0 ok
- *  -1 out of memory
- *  -2 interrupted
- *   1 not enough data points
- *************************************************************/
 #include <grass/cluster.h>
 
+/*!
+  \param maxclass maximum number of classes
+  \param iterations maximum number of iterations
+  \param convergence percentage of points stable
+  \param separation minimum distance between class centroids
+  \param checkpoint routine to be called at various steps
+  \param interrupted boolean to check for interrupt
+
+  \return 0 ok
+  \return -1 out of memory
+  \return -2 interrupted
+  \return 1 not enough data points
+*/
 int I_cluster_exec(struct Cluster *C, int maxclass, int iterations,
 		   double convergence,
 		   double separation, int min_class_size,
@@ -32,7 +38,7 @@ int I_cluster_exec(struct Cluster *C, int maxclass, int iterations,
 
     /* check for valid inputs */
     if (C->npoints < 2) {
-	fprintf(stderr, "cluster: not enough data points (%d)\n", C->npoints);
+	G_warning(_("Not enough data points (%d) in cluster"), C->npoints);
 	return 1;
     }
 

lib/cluster/c_execmem.c

@@ -1,11 +1,31 @@
+/*!
+  \file cluster/c_execmem.c
+  
+  \brief Cluster library - Allocate cluster
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <grass/cluster.h>
 
+/*!
+  \brief Allocate Cluster structure
+
+  \param C poiter to Cluster structure
+
+  \return 1 on success
+  \return 0 on error
+*/
 int I_cluster_exec_allocate(struct Cluster *C)
 {
-    /*
-       fprintf(stderr,"I_cluster_exec_allocate(npoints=%d,nclasses=%d,nbands=%d)\n", C->npoints, C->nclasses, C->nbands);
-     */
-
+    G_debug(1, "I_cluster_exec_allocate(npoints=%d,nclasses=%d,nbands=%d)",
+	    C->npoints, C->nclasses, C->nbands);
+    
     C->class = I_alloc_int(C->npoints);
     C->reclass = I_alloc_int(C->nclasses);
     C->count = I_alloc_int(C->nclasses);
@@ -24,6 +44,13 @@ int I_cluster_exec_allocate(struct Cluster *C)
     return 1;
 }
 
+/*!
+  \brief Free allocated Cluster structure
+
+  \param C pointer to Cluster structure
+
+  \return 0
+*/
 int I_cluster_exec_free(struct Cluster *C)
 {
     I_free(C->class);

lib/cluster/c_means.c

@@ -1,6 +1,26 @@
+/*!
+  \file cluster/c_means.c
+  
+  \brief Cluster library - Means value
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <math.h>
 #include <grass/cluster.h>
 
+/*!
+  \brief Calculate means value
+
+  \param C pointer to Cluster structure
+
+  \return 0
+*/
 int I_cluster_means(struct Cluster *C)
 {
     int band;
@@ -8,9 +28,9 @@ int I_cluster_means(struct Cluster *C)
     double m, v;		/* m=mean, v=variance then std dev */
     double s;
 
-    /*
-       fprintf(stderr,"I_cluster_means(nbands=%d,nclasses=%d)\n",C->nbands, C->nclasses);
-     */
+    G_debug(3, "I_cluster_means(nbands=%d,nclasses=%d)",
+	    C->nbands, C->nclasses);
+    
     for (band = 0; band < C->nbands; band++) {
 	s = C->band_sum[band];
 	m = s / C->npoints;

lib/cluster/c_merge.c

@@ -1,5 +1,25 @@
+/*!
+  \file cluster/c_merge.c
+  
+  \brief Cluster library - Merge
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <grass/cluster.h>
 
+/*!
+  \brief ?
+  
+  \param pointer to Cluster structure
+
+  \return 0
+*/
 int I_cluster_merge(struct Cluster *C)
 {
     int band, p;

lib/cluster/c_nclasses.c

@@ -1,5 +1,26 @@
+/*!
+  \file cluster/c_nclasses.c
+  
+  \brief Cluster library - Number of classes
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <grass/cluster.h>
 
+/*!
+  \brief Get number of classes
+
+  \param C pointer to Cluster structure
+  \param minsize minimum class size
+
+  \return number of classes
+*/
 int I_cluster_nclasses(struct Cluster *C, int minsize)
 {
     int i, n;

lib/cluster/c_point.c

@@ -1,21 +1,15 @@
-
-/****************************************************************
- * I_cluster_point (C,x)
- *     struct Cluster *C;
- *     DCELL *x;
- *
- * adds the point x to the list of data points to be "clustered"
- *
- * returns
- *   0  ok
- *  -1  out of memory, point not added
- *   1  all values are zero, point not added
- *
- * the dimension of x must agree with the number of bands specified
- * in the initializing call to I_cluster_begin()
- *
- * note: if all values in x are zero, the point is rejected
- ***************************************************************/
+/*!
+  \file cluster/c_point.c
+  
+  \brief Cluster library - Add point 
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
 
 #include <grass/raster.h>
 #include <grass/cluster.h>
@@ -23,6 +17,18 @@
 static int extend(struct Cluster *, int);
 static int all_zero(struct Cluster *, int);
 
+/*!
+  \brief Adds the point x to the list of data points to be "clustered"
+  
+  The dimension of x must agree with the number of bands specified
+  in the initializing call to I_cluster_begin()
+  
+  Note: if all values in x are zero, the point is rejected
+  
+  \return 0 ok
+  \return -1 out of memory, point not added
+  \return 1 all values are null, point not added
+*/
 int I_cluster_point(struct Cluster *C, DCELL * x)
 {
     int band;
@@ -53,11 +59,32 @@ int I_cluster_point(struct Cluster *C, DCELL * x)
     return 0;
 }
 
+/*!
+  \brief Begin point set
+
+  \param C pointer to Cluster structure
+  \param n ?
+
+  \return 0 on success
+  \return -1 on error
+*/
 int I_cluster_begin_point_set(struct Cluster *C, int n)
 {
     return extend(C, n) ? 0 : -1;
 }
 
+/*!
+  \brief ?
+
+  \param C pointer to Cluster structure
+  \param x cell value
+  \param band band number
+  \param n ?
+
+  \return 0 ok
+  \return -1 out of memory, point not added
+  \return 1 all values are null, point not added
+*/  
 int I_cluster_point_part(struct Cluster *C, DCELL x, int band, int n)
 {
     DCELL tmp = x;
@@ -71,6 +98,14 @@ int I_cluster_point_part(struct Cluster *C, DCELL x, int band, int n)
     return 0;
 }
 
+/*!
+  \brief ?
+
+  \param C pointer to Cluster structure
+  \param n ?
+
+  \return number of points
+*/
 int I_cluster_end_point_set(struct Cluster *C, int n)
 {
     int band;

lib/cluster/c_reassign.c

@@ -1,6 +1,27 @@
+/*!
+  \file cluster/c_reassign.c
+  
+  \brief Cluster library - Reassign cluster
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <math.h>
 #include <grass/cluster.h>
 
+/*!
+  \brief ?
+
+  \param C pointer to Cluster structure
+  \param interrupted
+
+  \return number of changes
+*/
 int I_cluster_reassign(struct Cluster *C, int *interrupted)
 {
     double min, d, z;

lib/cluster/c_reclass.c

@@ -1,5 +1,27 @@
+/*!
+  \file cluster/c_reclass.c
+  
+  \brief Cluster library - Reclass data
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <grass/cluster.h>
 
+/*!
+  \brief Reclass data
+
+  \param C pointer to Cluster structure
+  \param minsize minimum class size
+
+  \return 0 on success
+  \return 1 no change
+*/
 int I_cluster_reclass(struct Cluster *C, int minsize)
 {
     int band, c, hole, move, p;

lib/cluster/c_sep.c

@@ -1,8 +1,28 @@
+/*!
+  \file cluster/c_sep.c
+  
+  \brief Cluster library - Separation
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <math.h>
 #include <grass/cluster.h>
 
 #define FAR ((double) -1.0)
 
+/*!
+  \brief ?
+
+  \param C pointer to Cluster structure
+  \param class1 1st class
+  \param class2 2nd class
+*/
 double I_cluster_separation(struct Cluster *C, int class1, int class2)
 {
     int band;

lib/cluster/c_sig.c

@@ -1,4 +1,25 @@
+/*!
+  \file cluster/c_sig.c
+  
+  \brief Cluster library - Signatures
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <grass/cluster.h>
+
+/*!
+  \brief Create signatures
+
+  \param C pointer to Cluster structure
+
+  \return 0
+*/
 int I_cluster_signatures(struct Cluster *C)
 {
     int c, p, band1, band2;

lib/cluster/c_sum2.c

@@ -1,14 +1,33 @@
+/*!
+  \file cluster/c_sum2.c
+  
+  \brief Cluster library - Sum of squares
+  
+  (C) 2001-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Original author CERL
+*/
+
 #include <grass/cluster.h>
 
-/* compute sum of squares for each class */
+/*!
+  \brief Compute sum of squares for each class
+
+  \param C pointer to Cluster structure
+
+  \return 0
+*/
 int I_cluster_sum2(struct Cluster *C)
 {
     int p, band, class;
     double q;
 
-    /*
-       fprintf (stderr, "I_cluster_sum2(npoints=%d,nclasses=%d,nbands=%d)\n", C->npoints, C->nclasses, C->nbands);
-     */
+    G_debug(3, "I_cluster_sum2(npoints=%d,nclasses=%d,nbands=%d)",
+	    C->npoints, C->nclasses, C->nbands);
+    
     for (class = 0; class < C->nclasses; class++)
 	for (band = 0; band < C->nbands; band++)
 	    C->sum2[band][class] = 0;

lib/cluster/clusterlib.dox

@@ -1,8 +1,86 @@
-/*! \page clusterlib GRASS cluster analysis statistics Library
+/*! \page clusterlib GRASS Cluster analysis statistics Library
 
-\section clusterintro Introduction to cluster analysis statistics Library
+by GRASS Development Team (http://grass.osgeo.org)
 
-This library does a k-means style of cluster analysis.
-It is currently only used by i.cluster.
+\section clusterintro Introduction
+
+This library does a k-means style of cluster analysis. It is currently
+only used by <tt>i.cluster</tt>.
+
+The library functions are defined in <tt>cluster.h</tt>.
+
+\code
+#include <grass/cluster.h>
+\endcode
+
+\section ClusterStruct Cluster structure
+
+\code
+struct Cluster
+{
+    int nbands;                 /* number of bands */
+    int npoints;                /* number of points */
+    DCELL **points;             /* array of points */
+    int np;
+
+    double *band_sum;		/* sum over each band */
+    double *band_sum2;		/* sum of squares over each band */
+
+    int *class;			/* class of each point */
+    int *reclass;		/* for removing empty classes  */
+    int *count;			/* number of points in each class */
+    int *countdiff;		/* change in count */
+    double **sum;		/* sum over band per class */
+    double **sumdiff;		/* change in sum */
+    double **sum2;		/* sum of squares per band per class */
+    double **mean;		/* initial class means */
+    struct Signature S;		/* final signature(s) */
+
+    int nclasses;               /* number of classes */
+    int merge1, merge2;
+    int iteration;              /* number of iterations */
+    double percent_stable;      /* percentage stable */
+};
+\endcode
+
+\section listFn List of functions
+
+ - I_cluster_assign()
+
+ - I_cluster_begin()
+
+ - I_cluster_clear()
+
+ - I_cluster_distinct()
+
+ - I_cluster_exec()
+
+ - I_cluster_exec_allocate()
+
+ - I_cluster_exec_free()
+
+ - I_cluster_means()
+
+ - I_cluster_merge()
+
+ - I_cluster_nclasses()
+
+ - I_cluster_point()
+
+ - I_cluster_begin_point_set()
+
+ - I_cluster_point_part()
+
+ - I_cluster_end_point_set()
+
+ - I_cluster_reassign()
+
+ - I_cluster_reclass()
+
+ - I_cluster_separation()
+
+ - I_cluster_signatures()
+
+ - I_cluster_sum2()
 
 */