Initial port to GitHub

README.md

@@ -1,4 +1,20 @@
-caltech-lane-detection
-======================
-
 Caltech Lane Detection Software
+===============================
+
+This package contains C/C++ and Matlab source code that implements the work in [1]. It implements a real time lane detection system for single images by fitting robust Bezier splines. It can detect all lanes in the street, or the two lane markers of the current lane. To quickly see it in action, download the software below and also the Caltech Lanes Dataset .
+
+The detection runs in real time, about 40-50 Hz and detects all lanes in the street. It was compiled and tested on Ubuntu Lucid Lynx 32-bit machine and Red Hat Enterprise Linux 5.5 64-bit machine.
+
+It also includes several functionalities that were missing from OpenCV at the time, including:
+
+Routines for obtaining the Inverse Perspective Mapping (IPM) of an image i.e. getting a bird's eye view of the road.
+Routines for conversion to/from image pixel coordinates and coordinates on the road plane (using the ground plane assumption).
+Robust & RANSAC line fitting.
+Robust & RANSAC Bezier spline fitting.
+Bezier spline rasterization and plotting.
+Bresenham's line raterization.
+
+Various utility functions for checking intersections of lines with lines and bounding boxes, checking points inside a rectangle, ... etc.
+An implementation of a general Hough transform routine for lines.
+
+[1] Mohamed Aly, Real time Detection of Lane Markers in Urban Streets, IEEE Intelligent Vehicles Symposium, Eindhoven, The Netherlands, June 2008. [pdf]

README.md~

@@ -0,0 +1,4 @@
+caltech-lane-detection
+======================
+
+Caltech Lane Detection Software

README.txt

@@ -0,0 +1,152 @@
+# Author: Mohamed Aly <[email protected]>
+# Date: 10/7/2010
+
+============================================================================
+                     REAL TIME LANE DETECTOR SOFTWARE
+============================================================================
+
+This package contains source code and dataset that implements the work in the
+paper [1].
+
+=========
+Contents
+=========
+src/: contains the C/C++ source files
+
+|_ CameraInfo.conf: contains the camera calibration ifo
+
+|_ CameraInfoOpt.*: contain gengetopt files for parsing the camera info files
+
+|_ cmdline.*: contains gengetopt files for parsing command lines
+
+|_ InversePerspectiveMapping.*: code for obtainig the IPM of an image
+
+|_ LaneDetector.*: code for the bulk of the algorithm, including Hough
+      Transforms, Spline fitting, Post processing, ...
+
+|_ Lanes.conf: the typical configuration file for lane detection
+
+|_ main.*: code for the main binary
+
+|_ Makefile: the Make file
+
+|_ mcv.*: contain utility functions
+
+|_ ranker.h: code for obtaining the median of a vector
+
+|_ run.sh: Shell script for running the detector on the four clips in
+    Caltech Lanes Dataset
+
+matlab/: contains the Matlab source files
+
+|_ ccvCheckMergeSplines.m: checks if two splines are matching
+
+|_ ccvEvalBezSpline.m: returns points on a spline given its control points
+
+|_ ccvGetLaneDetectionStats.m: computes stats from detections and ground truth
+
+|_ ccvLabel.m: handles the ground truth labels
+
+|_ ccvReadLaneDetectionResultsFile.m: reads a detection file output from the
+    binary file LaneDetector32/64
+
+|_ Stats.m: computes stats for the detections on the Caltech Lanes Dataset and
+    its ground truth labels
+
+==============
+Prerequisites
+==============
+1. OpenCV 2.0 or higher http://sourceforge.net/projects/opencvlibrary/
+3. (Optional) Gengetopt http://www.gnu.org/software/gengetopt/
+
+===========
+Compiling
+===========
+Unzip the archive somewhere, let's say ~/lane-detector:
+
+unzip lane-detector.zip -d ~/lane-detector
+cd ~/lane-detector/src
+make release
+
+This will generate LaneDetector32 or LaneDetector64 depending on your system.
+
+======================
+Caltech Lanes Dataset
+======================
+To view the lane detector in action, you can download the Caltech Lanes Dataset
+available at http://www.vision.caltech.edu/malaa/datasets/caltech-lanes
+
+===========
+Running
+===========
+To run the detector on the Caltech Lanes dataset, which might be in
+~/caltech-lanes/
+
+cd ~/lane-detector/
+ln -s ~/caltech-lanes/  clips
+cd ~/lane-detector/src/
+bash run.sh
+
+This will create the results files inside
+~/caltech-lanes/*/list.txt_results.txt
+
+To view the statistics of the results, open Matlab and run the file:
+
+cd ~/lane-detector/matlab/
+matlab&
+>>Stats
+
+======================
+Command line options
+======================
+LinePerceptor 1.0
+
+Detects lanes in street images.
+
+Usage: LinePerceptor [OPTIONS]... [FILES]...
+
+  -h, --help                   Print help and exit
+  -V, --version                Print version and exit
+
+Basic options:
+      --lanes-conf=STRING      Configuration file for lane detection
+                                 (default=`Lanes.conf')
+      --stoplines-conf=STRING  Configuration file for stopline detection
+                                 (default=`StopLines.conf')
+      --no-stoplines           Don't detect stop lines  (default=on)
+      --no-lanes               Don't detect lanes  (default=off)
+      --camera-conf=STRING     Configuration file for the camera paramters
+                                 (default=`CameraInfo.conf')
+      --list-file=STRING       Text file containing a list of images one per
+                                 line
+      --list-path=STRING       Path where the image files are located, this is
+                                 just appended at the front of each line in
+                                 --list-file  (default=`')
+      --image-file=STRING      The path to an image
+
+Debugging options:
+      --wait=INT               Number of milliseconds to show the detected
+                                 lanes. Put 0 for infinite i.e. waits for
+                                 keypress.  (default=`0')
+      --show                   Show the detected lines  (default=off)
+      --step                   Step through each image (needs a keypress) or
+                                 fall through (waits for --wait msecs)
+                                 (default=off)
+      --show-lane-numbers      Show the lane numbers on the output image
+                                 (default=off)
+      --output-suffix=STRING   Suffix of images and results
+                                 (default=`_results')
+      --save-images            Export all images with detected lanes to the by
+                                 appending --output-suffix + '.png' to each
+                                 input image  (default=off)
+      --save-lanes             Export all detected lanes to a text file by
+                                 appending --output-suffix + '.txt' to
+                                 --list-file  (default=off)
+      --debug                  Show debugging information and images
+                                 (default=off)
+
+===========
+References
+===========
+[1] Mohamed Aly, Real time Detection of Lane Markers in Urban Streets,
+  IEEE Intelligent Vehicles Symposium, Eindhoven, The Netherlands, June 2008.

matlab/Stats.m

@@ -0,0 +1,28 @@
+function Stats
+% STATS computes stats for the results of LaneDetector
+%
+% Inputs:
+% -------
+% 
+% Outputs:
+% --------
+%
+
+% The detection files
+detectionFiles = {
+  '../clips/cordova1/list.txt_results.txt'
+  '../clips/cordova2/list.txt_results.txt'
+  '../clips/washington1/list.txt_results.txt'
+  '../clips/washington1/list.txt_results.txt'
+  };
+
+% The ground truth labels
+truthFiles = {
+  '../clips/cordova1/labels.ccvl'
+  '../clips/cordova2/labels.ccvl'
+  '../clips/washington1/labels.ccvl'
+  '../clips/washington1/labels.ccvl'
+  };
+
+% Get statistics
+ccvGetLaneDetectionStats(detectionFiles, truthFiles);

matlab/ccvCheckMergeSplines.m

@@ -0,0 +1,51 @@
+function merge = ccvCheckMergeSplines(spline1, spline2, meanDistThreshold, ...
+  medianDistThreshold)
+% CCVCHECKMERGESPLINES checks if two splines are to be merged (matched) or
+% not. It does this by computing the distance from every point in each
+% spline to every other point in the other spline and checking that the mean 
+% or median distances are below the given thresholds.
+%
+% Inputs:
+% -------
+% spline2: Nx2 matrix of spline control points
+% spline2: Nx2 matrix of spline control points
+% meanDistThreshold: threshold for the mean distance between points on the
+%   two splines
+% medianDistThreshold: threshold for median distance between points on the
+%   two splines
+% 
+% Outputs:
+% --------
+% merge: 1 if to merge, 0 otherwise
+%
+
+%get points on both
+p1 = ccvEvalBezSpline(spline1, .01);
+p2 = ccvEvalBezSpline(spline2, .01);
+
+%now for every point in spline1, compute nearest in spline2, and get that
+%distance
+dist1 = zeros(1, size(p1,1));
+for i=1:size(p1, 1)
+    %get diff
+    d = repmat(p1(i,:), size(p2, 1), 1) - p2;
+    %get distance
+    d = sqrt(sum(d.^2, 2));
+    %get min
+    dist1(i) = min(d);
+end;
+dist2 = zeros(1, size(p2,1));
+for i=1:size(p2, 1)
+    %get diff
+    d = repmat(p2(i,:), size(p1, 1), 1) - p1;
+    %get distance
+    d = sqrt(sum(d.^2, 2));
+    %get min
+    dist2(i) = min(d);
+end;
+
+%compute mean and median
+meanDist = min(mean(dist1), mean(dist2));
+medianDist = min(median(dist1), median(dist2));
+
+merge = (meanDist <= meanDistThreshold) || (medianDist <= medianDistThreshold);

matlab/ccvEvalBezSpline.m

@@ -0,0 +1,100 @@
+function [outPoints, tangent] = ccvEvalBezSpline(spline, h)
+% ccvEvalBezSpline evaluates a Bezier spline with the specified degree
+
+% INPUTS
+% ------
+% spline    - input 3 or 4 points in a matrix 3x2 or 4x2 [xs, ys]
+% h         - [0.05] the interval to use for evaluation
+% 
+% OUTPUTS
+% -------
+% outPoints - output points nx2 [xs; ys]
+% tangent   - the tangent at the two end-points [t0; t1]
+%
+% EXAMPLE
+% -------
+% [p, t] = ccvEvalBezSpline(sp, 0.1);
+% 
+% See also ccvDrawBezSpline
+
+if nargin<2, h = 0.05; end
+
+%get the degree
+degree = size(spline, 1) - 1;
+
+%compute number of return points
+n = floor(1/h)+1;
+
+%degree
+switch degree
+	%Quadratic Bezier curve
+	case 2
+		M =	[1,	-2,	1; ...
+			-2,	2,	0; ...
+			1,	0,	0];
+
+		%compute constants [a, b, c]
+		abcd = M * spline;
+		a = abcd(1,:);	b = abcd(2,:);	c = abcd(3,:);
+
+		%compute at time 0
+		P = c;
+		dP = b * h + a * h^2;
+		ddP = 2*a*h^2;
+
+		%loop
+		outPoints = zeros(n, size(spline,2));
+		outPoints(1,:) = P;
+		for i=2:n
+			%calculate new point
+			P = P + dP;
+			%update steps
+			dP = dP + ddP;
+			%put back
+			outPoints(i,:) = P;
+		end;
+
+		%tangents: t0 = b
+		t0 = b;
+		%t1 = 2a+b
+		t1 = 2*a+b;
+
+	%Cubic Bezier curve
+	case 3
+		M =	[-1,	3,		-3,		1; ...
+			3,		-6,		3,		0; ...
+			-3,		3,		0,		0; ...
+			1,		0,		0,		0];
+
+		%compute constants [a, b, c, d]
+		abcd = M * spline;
+		a = abcd(1,:);	b = abcd(2,:);	c = abcd(3,:);	d = abcd(4,:);
+
+		%compute at time 0
+		P = d;
+		dP = c*h + b * h^2 + a * h^3;
+		ddP = 2*b*h^2 + 6*a*h^3;
+		dddP = 6*a*h^3;
+
+		%loop
+		outPoints = zeros(n, size(spline,2));
+		outPoints(1,:) = P;
+		for i=2:n
+			%calculate new point
+			P = P + dP;
+			%update steps
+			dP = dP + ddP;
+			ddP = ddP + dddP;
+			%put back
+			outPoints(i,:) = P;
+		end;
+
+		%tangents: t0 = c
+		t0 = c;
+		%t1 = 3a+2*b+c
+		t1 = 3*a+2*b+c;
+end;
+
+%put tangents together
+tangent = [t0; t1];
+