Changeset 217

Timestamp:

09/28/08 16:52:19 (3 years ago)

Author:

spenceal

Message:

commenting vision.h, moving jaus code

Location:

trunk/software/rb

Files:

• jaus (added)
• jaus/jaus.py (copied) (copied from trunk/software/rb/vision/jaus.py)
• vision/pathplan.c (modified) (1 diff)
• vision/vision.h (modified) (3 diffs)

trunk/software/rb/vision/pathplan.c

@@ -115 +115 @@
                                                 lines[cur_line].end.x = xe;
                                                 lines[cur_line].end.y = ye;
-                                                lines[cur_line].len = sqrt((xs-xe)*(xs-xe) + (ys-ye)*(ys-ye));
                                                 cur_line++;
                                         }

trunk/software/rb/vision/vision.h

@@ -27 +27 @@
         CvPoint start;
         CvPoint end;
-        int len;
 } CvLine;
 
@@ -33 +32 @@
 
 /* Structs and constants */
-/* Pixle byte orders */
+/*
+ * Pixel byte orders
+ * This represents the orders in which OpenCV stores pixels
+ * The union lets us access everything as the same type but still use sensical
+ * names
+ */
 typedef union {
-        struct { 
-                uint8_t b;
-                uint8_t g;
-                uint8_t r;
+        struct {
+                uint8_t b; // Blue
+                uint8_t g; // Green
+                uint8_t r; // Red
         } __attribute__ ((packed)) bgr;
         struct {
-                uint8_t h;
-                uint8_t s;
-                uint8_t v;
+                uint8_t h; // Hue
+                uint8_t s; // Saturation
+                uint8_t v; // Value
         } __attribute__ ((packed)) hsv;
 } __attribute__ ((packed)) px_t;
 
-/* limits on pixel values, used for threshnold stuff */
+/*
+ * Limits on pixel values, used for threshnold stuff
+ *
+ * For a pixel to be classified as beloging to `target' it must be inbetween
+ * min and max. We use HSV for this because it allows us to cluster things more
+ * effectively than BGR.
+ */
 typedef struct {
         uint8_t hue_min; uint8_t hue_max;
         uint8_t sat_min; uint8_t sat_max;
         uint8_t val_min; uint8_t val_max;
-        px_t target; // What to set this pixel to if it's found
+        px_t target;
 } px_params_t;
 
-/* Callback function for classifying pixles */
+/*
+ * Callback function tyep for classifying pixels
+ *
+ * Actual callback functions should be named get_<what> where what represents
+ * the thing that thye classify.
+ *
+ * \param in        Raw input imaged (check this)
+ * \param out       Image as it has been clasified so far (check this)
+ * \param x         X value of the pixle to look at
+ * \param y         Y value of the pixle to look at
+ * \param px_params Parameters to classify based on
+ * \retval A PX_??? that represents how pixle (x,y) should be classified
+ */
 typedef px_t (*get_type_cb_t)(const IplImage *, IplImage *, int, int,
                               px_params_t);
 
-/* Standard pixel values */
+/*
+ * Standard pixel values
+ *
+ * The classified image will be represented by these colors
+ */
 const static px_t PX_SKY      = {.bgr = {.r =  0, .g =  0, .b = -1}}; // Blue
 const static px_t PX_GRASS    = {.bgr = {.r =  0, .g = -1, .b =  0}}; // Green
@@ -69 +95 @@
 
 
-/* Function API */
-/* Utiltiies */
+/*** Function API ***/
+
+/**
+ * Utilities
+ **/
+
+/*
+ * Find the first non-grass point starting at `start'
+ * Each time, increment y by `1' and x by `x_inc',
+ *
+ * This is useful for determining how far the robot could move from point
+ * `start' in a particlar directoin before running into an obsticle.
+ */
 CvPoint  find_obsticle     (IplImage *out, CvPoint2D32f start, float x_inc);
+
+/*
+ * Determine if the path between points `start' and `end' is clear. That is,
+ * returnt true if and only if every point between start and end consists of
+ * grass.
+ */
 int      is_clear          (IplImage *out, CvPoint start, CvPoint end);
+
+/*
+ * Return a point leftmost occurance of `target' at a particular horizontal (y)
+ * line. This scanns all points (x = 0..width, y = y_line) in the image `out'
+ * and returns the first point that is of the type `target.
+ */
 CvPoint  find_px_at_y      (IplImage *out, int y_line, px_t target);
+
+/*
+ * Attempt to find fit a slope to a line in a given box.
+ *
+ * The goal of this function is to return a mathematical representation of a
+ * course boundry so that the slope of a line at that point can be exteded in
+ * order to fill in gaps that occure in the line.
+ */
 double   find_slope_in_box (IplImage *out, CvRect box,
                             go_regression_stat_t *reg);
 
-/* runs callback for mark_* */
+/*
+ * Runs callback functions for mark_*
+ *
+ * Each callback funcion only specifies the type for a particular pixle. This
+ * function loops though all pixels in the input image in order to generate a
+ * complete output image. It calls `get_type_cb' once for each pixle in the
+ * image.
+ *
+ * \param in          Input  image in HSV colorspace
+ * \param out         Output image in BGR colorspace
+ * \param px_params   Pixel parameters to pass to the get_type_cb function.
+ *                    This allows the same get_type_cb to be tweeked for the
+ *                    particular color of the grass/lines, etc.
+ * \param get_type_cb The callback function to call for each pixel.
+ */
 px_t     mark_type         (const IplImage *in, IplImage *out,
                             px_params_t px_params, get_type_cb_t get_type_cb);
 
 
-/* Grass/obsticle/sky finding */
+
+/**
+ * Grass, Sky, Obsticle finding
+ **/
+
+/*
+ * Callback function for detecting grass, sky, and obsticles.
+ *
+ * This is the first callback issued. It works by determining if the pixel in
+ * question matches the given pixel parameters, if so it is designated as
+ * grass, otherwise it is designated as an obsticle.
+ *
+ * The exception to this is if the pixel is above the horizon, in that case it
+ * is designated as sky.
+ *
+ * See get_type_cb_t for parameter details
+ */
 px_t     get_grass         (const IplImage *in, IplImage *out, int x, int y,
                             px_params_t px_params);
+
+// TODO: Discuss the flow (mark_grass -> mark_type -> get_grass)
+/*
+ * Mark all grass in the input image as grass in the output image.
+ *
+ * For any pixel in the input image that is grass write a green pixel to the
+ * output image.
+ */
 void     mark_grass        (const IplImage *in, IplImage *out);
 
-/* Line finding */
+
+
+/**
+ * Line finding
+ **/
+
+/*
+ * Determine whether a pixel is a line. This based mostly on the HSV value of
+ * the pixels but also does some more advanced logic to prevent barrels and
+ * such from being incorrectly shown as lines.
+ *
+ * See get_type_cb_t for parameter details
+ */
 px_t     get_lines         (const IplImage *in, IplImage *out, int x, int y,
                             px_params_t px_params);
+
+/*
+ * Mark all lines as in the image, this may call call get_type/get_lines for
+ * both white and yellow lines.
+ */
 void     mark_lines        (const IplImage *in, IplImage *out);
+
+/*
+ * Expand lines to fill gaps
+ *
+ * This expands lines so that small areas in the lines that were missed get
+ * filled in. This also helps to keep the robot a little bit away from the
+ * actual line.
+ */
 void     expand_lines      (const IplImage *o1, IplImage *o2);
+
+/*
+ * This partitions the image into a grid of boxes and attempts to draw the
+ * slope of the white line in each box. This is mostly used for debugging
+ * find_slope_in_box at the moment.
+ */
 void     mark_slopes       (IplImage *out);
 
-/* Path planning */
-CvPoint  get_path_strait   (IplImage *out, CvPoint goal);
-CvPoint  get_path_left     (IplImage *out, int dist_limit);
-CvLine  *get_path_curvey   (IplImage *out, CvPoint goal, int *nlines);
-
-/* Debuggin */
+
+
+/**
+ * Debuggin
+ **/
+
+/*
+ * Print out an image in a textual format so that it can be imported into other
+ * software such as gnuplot or Weka.
+ */
 void print_image(IplImage *img);
+
+/*
+ * Prints out the given label as well as a timestamps for the current time.
+ * This is used for profiling the software
+ */
 void print_time(char *label);
 
 
 
-/* Pixel access functions */
+/**
+ * Pixel access functions
+ *
+ * IplImages as a 1d array of bytes, this makes it slightly tricky because each
+ * pixel is 3 bytes and offsets have to be calculated manually.
+ **/
+
+/*
+ * Determine whether px1 is identical to px2
+ */
 inline int   IS_PX(px_t px1, px_t px2);
+
+/*
+ * Fetch a pixel out of an IplImage.
+ */
 inline px_t GET_PX(const IplImage *img, int x, int y);
+
+/*
+ * Set a pixel (x,y) in the IplImage to `val'
+ */
 inline void SET_PX(IplImage *img, int x, int y, px_t val);