import code frm v0.6

LICENSE → COPYING

@@ -633,8 +633,8 @@ the "copyright" line and a pointer to where the full notice is found.
     Copyright (C) <year>  <name of author>
 
     This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Affero General Public License as published
-    by the Free Software Foundation, either version 3 of the License, or
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
 
     This program is distributed in the hope that it will be useful,

Makefile

@@ -0,0 +1,8 @@
+# lazy makefile
+PROG=detect_vps
+all:
+	$(MAKE) -C mex_files/ all
+	mcc -m ${PROG}.m -a mex_files/ -a mixtures/ -a lib/  -R -nodisplay
+
+
+

README.txt

@@ -0,0 +1,109 @@
+Vanishing Points detection 
+==========================
+version 0.6 - July 2015
+by Jose Lezama <jlezama@gmail.com>
+
+
+Introduction
+------------
+
+This code implements the vanishing point detection algorithm as described in the IPOL article
+ "Vanishing Point Detection in Urban Scenes Using Point Alignments" Jose Lezama, Gregory Randall, Jean-Michel Morel and Rafael Grompone von Gioi. 
+
+Optionally, this code uses the algorithm by Figueiredo and Jain, Unsupervised 
+learning of finite mixture models, to quickly obtain cluster candidates.
+
+Files and Folders
+-----------------
+
+README.txt             - This file
+COPYING                - GNU AFFERO GENERAL PUBLIC LICENSE Version 3
+Makefile               - Compilation instructions for 'make'
+main.m		       - demo script
+detect_vps.m	       - main algorithm script
+yud_benchmark.m	       - script to run benchmark scores in York Urban Database
+ecd_benchmark.m	       - script to run benchmark scores in Eurasian Citites Database
+test.jpg	       - test image
+lib/		       - folder with auxiliary MATLAB scripts
+mex_files/	       - folder with C sources for line segment and point alignment detection, to be compiled as mex files
+mixtures/	       - folder with the unsupervised mixtures detection code of Figueiredo and Jain, which can optionally be used for accelerating the method
+
+
+Compiling
+---------
+
+The algorithm depends on three mex scripts that need to be compiled before
+execution. For compilation inside MATLAB, cd into the 'mex_files' folder and run
+build.m
+
+Optional: run make to produce compiled matlab executables
+
+Running
+-------
+
+For a test run on the test image, run main.m
+main.m calls the main function, detect_vps.m
+Arguments of detect_vps.m are:
+ - img_in: filename of the input image
+ - folder_out: path to save resulting image and text files
+ - manhattan: boolean variable used to determine if the Manhattan-world
+   hypothesis is assumed
+ - acceleration: boolean variable used to determine if acceleration using
+   Figueiredo and Jain GMM algorithm should be used
+ - focal_ratio: ratio between the focal lenght and captor width
+ - input_params: optional input parameters
+
+
+Benchmarks
+----------
+
+To run benchmarks on York Urban Dataset (YUD) and Eurasian Cities Dataset (ECD)
+run yud_benchmark.m and ecd_benchmark.m. You should obtain results similar or
+better to the ones reported in our CVPR paper.
+
+Note that without the acceleration the scripts can be slow. In particular for
+ECD the non-accelerated version can take up to 3 minutes per image (there are
+103 images in that dataset).
+
+The datasets are not provided but can be obtained from the following sites:
+
+YUD, by P. Denis: http://www.elderlab.yorku.ca/YorkUrbanDB/
+ECD, by O. Barinova: http://graphics.cs.msu.ru/en/research/projects/msr/geometry
+
+
+Acceleration
+------------
+
+As an optional procedure, an accelerated version of the algorithm can be run by
+setting the appropiate flag (see detect_vps.m). This version uses Figueiredo's
+"Unsupervised Learning of Finite Mixture Models" algorithm to quickly obtain
+cluster candidates.  
+
+The scripts files, available at the author's website (http://www.lx.it.pt/~mtf/)
+are included, and have been slightly modified for speed improvement.
+
+
+Copyright and License
+---------------------
+
+Copyright (c) 2013-2015 Jose Lezama <jlezama@gmail.com>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+
+Thanks
+------
+
+We would be grateful to receive any comment, especially about errors,
+bugs, or strange results.

detect_vps.m

@@ -0,0 +1,180 @@
+function [horizon_line, vpimg] = detect_vps(img_in,folder_out,...
+    manhattan, acceleration, focal_ratio, input_params)
+
+% DETECT_VPS
+% Function for vanishing points and horizon line detection
+%
+% Version 0.5, February 2015
+%
+% arguments:
+% - img_in: filename of the input image
+% - folder_out: path to save resulting image and text files
+% - manhattan: boolean variable used to determine if the Manhattan-world
+%   hypothesis is assumed
+% - acceleration: boolean variable used to determine if acceleration using
+%   Figueiredo and Jain GMM algorithm should be used
+% - focal_ratio: ratio between the focal lenght and captor width
+% - input_params: optional input parameters
+%
+% output:
+% - horizon_line: estimated horizon line in image coordinates
+% - vpimg: esitmated vanishing points in image coordinates
+%
+% Copyright (C) 2015 Jose Lezama <jlezama@gmail.com>
+%
+% This program is free software: you can use, modify and/or
+% redistribute it under the terms of the GNU General Public
+% License as published by the Free Software Foundation, either
+% version 3 of the License, or (at your option) any later
+% version. You should have received a copy of this license along
+% this program. If not, see <http://www.gnu.org/licenses/>.
+%
+% This program is free software: you can use, modify and/or
+% redistribute it under the terms of the simplified BSD
+% License. You should have received a copy of this license along
+% this program. If not, see
+% <http://www.opensource.org/licenses/bsd-license.html>.
+%
+% To the extent possible under law, the authors have dedicated all
+% copyright and related and neighboring rights to this software to
+% the public domain worldwide. This software is distributed without
+% any warranty. You should have received a copy of the CC0 Public
+% Domain Dedication along with this software. If not, see
+% <http://creativecommons.org/publicdomain/zero/1.0/>.
+%
+% This program is provided for research and education only: you can
+% use and/or modify it for these purposes, but you are not allowed
+% to redistribute this work or derivative works in source or
+% executable form. A license must be obtained from the patent right
+% holders for any other use.
+
+if ~isdeployed
+    addpath lib
+end
+
+% input parameters
+if isdeployed
+    manhattan = str2num(manhattan);
+    acceleration = str2num(acceleration);
+    focal_ratio = str2num(focal_ratio);
+end
+
+
+if nargin < 6
+    input_params = struct();
+end
+
+params.MANHATTAN = manhattan;
+params.ACCELERATION = acceleration;
+params.img_in = img_in;
+params.folder_out = folder_out;
+
+if isdeployed
+    params.PLOT = 1;
+    params.PRINT = 1;
+else
+    params.PLOT = 0;
+    params.PRINT = 0;
+end
+
+% method parameters
+params.REFINE_THRESHOLD = 2; % (theta)
+params.VARIATION_THRESHOLD = .3; % (zeta)
+params.DUPLICATES_THRESHOLD = .05;%.3; % (delta)
+params.VERTICAL_ANGLE_THRESHOLD = 50; % (omega)
+params.INFINITY_THRESHOLD = 30; % (lambda)
+params.FOCAL_RATIO = focal_ratio; % (f)
+params.LENGTH_THRESHOLD = 1.71;; % (tau) final threshold will be sqrt(W+H)/tau
+params.DIST_THRESHOLD =.165;% (kappa)
+
+if params.MANHATTAN
+    % inclusive threshold
+    params.ORTHOGONALITY_THRESHOLD = cos(87.5*pi/180); % .058;
+else
+    % exclusive threshold
+    params.ORTHOGONALITY_THRESHOLD = cos(77.5*pi/180);%cos(75*pi/180);
+end
+
+
+% acceleration parameters
+params.MAX_POINTS_ACCELERATION = 200; % use acceleration if number of points is larger than this
+params.GMM_Ks = [30 30 30];
+
+% overwrite with optional input parameters
+names = fieldnames(input_params);
+for i=1:length(names)
+    v = getfield(input_params, names{i});
+    params = setfield(params, names{i}, v);
+end
+
+%% START SCRIPT
+
+% read image
+img = imread(img_in);
+[params.H, params.W, ~] = size(img);
+
+
+% length threshold based on image size
+params.LENGTH_THRESHOLD = sqrt((params.H+params.W))/params.LENGTH_THRESHOLD;
+
+
+% get line segments
+lines = run_lsd(img_in);
+lines_lsd = lines;
+
+% denoise lines
+[lines, line_endpoints] = denoise_lines(lines, params);
+
+if params.PRINT
+    draw_lines(lines, line_endpoints, params);
+
+
+end
+
+% convert to PClines
+[points_straight, points_twisted] = convert_to_PClines(lines, params);
+
+% run alignment detector in straight and twisted spaces
+[detections_straight, m1, b1] = find_detections(points_straight, params);
+[detections_twisted, m2, b2] = find_detections(points_twisted, params);
+
+
+% gather intial vanishing point detections
+[mvp_all, NFAs] = read_detections_as_vps(detections_straight, m1, b1, ...
+    detections_twisted, m2, b2, params);
+
+% refine detections
+mvp_all = refine_detections(mvp_all, lines_lsd, params);
+
+[mvp_all, NFAs] = remove_duplicates(mvp_all, NFAs,params);
+
+% draw preliminary detections
+if params.PRINT
+
+    img2 = draw_segments(img,mvp_all, lines_lsd, params);    
+
+    imwrite(img2,sprintf('%s/vps_raw.png',params.folder_out));
+end
+
+% compute horizon line
+if ~isempty(mvp_all);
+    if params.MANHATTAN
+        [horizon_line, vpimg] = compute_horizon_line_manhattan(mvp_all, NFAs, lines_lsd, params);
+    else
+        [horizon_line, vpimg] = compute_horizon_line_non_manhattan(mvp_all, NFAs, lines_lsd, params);
+    end
+else
+    horizon_line = [];
+    vpimg = [];
+    imwrite(img,sprintf('%s/horizon_line.png',params.folder_out));
+    fileID = fopen(sprintf('%s/out.txt',params.folder_out),'w');
+    fprintf(fileID,'No Vanishing Points found.\n');
+    fclose(fileID);
+end
+
+if params.PRINT
+    draw_dual_spaces(points_straight, detections_straight, 'straight', vpimg, params)
+    draw_dual_spaces(points_twisted, detections_twisted, 'twisted', vpimg, params)
+end
+
+disp('FINISHED.')

ecd_benchmark.m

@@ -0,0 +1,86 @@
+% Benchmark VP detection on Eurasian Cities Dataset
+%
+% This program is written by Jose Lezama <jlezama@gmail.com> and
+% distributed under the terms of the GPLv3 license.
+%
+% Eurasian Cities Dataset (ECD) by Olga Barinova
+% http://graphics.cs.msu.ru/en/research/projects/msr/geometry
+%
+% Reported performance should be close to  89.8% for the training set 
+% (first 25 images) and 89.6% for the test set
+
+clear
+close all
+
+tic
+
+% point the following path to your local copy of ECD
+DATASET_PATH = '/Users/jose/Documents/cmla/datasets/20130829_EurasianCitiesBase';
+
+dirlist = dir(sprintf('%s/*.jpg',DATASET_PATH));
+
+params.REFINE_THRESHOLD =  .62;% 0.375;
+params.VARIATION_THRESHOLD = .3;%.305;
+params.DUPLICATES_THRESHOLD = .0001;%.0039;
+params.DIST_THRESHOLD = .165;
+params.INFINITY_THRESHOLD = 3.58; % (lambda)
+
+focal_ratio = 1.08;% 1.05;
+
+
+all_errors = zeros(size(dirlist));
+
+PLOT = 0;
+
+for f = 26:103%1:length(dirlist)
+    % load image and ground truth
+    img_filename = sprintf('%s/%s',DATASET_PATH, dirlist(f).name);
+    mat_filename = sprintf('%s/%shor.mat',DATASET_PATH, dirlist(f).name(1:end-4));
+
+    img = imread(img_filename);
+    [H, W, ~] = size(img);
+
+    if PLOT
+        img = imread(img_filename);
+        [H, W, ~] = size(img);
+        figure, imagesc(img)
+    end
+
+    manhattan = 0;
+    acceleration = 1;    
+
+    % compute  horizon line detection
+    horizon_line_ours = detect_vps(img_filename, '.', manhattan, acceleration, focal_ratio, params);
+
+
+    % load ground truth
+    load(mat_filename)
+
+    % compute horizon line estimation error
+    X = [1 W];
+    P_gt = [-horizon(1)/horizon(2) -horizon(3)/horizon(2)];
+    Y_gt = polyval(P_gt,X);
+    Y_ours = [horizon_line_ours(1) horizon_line_ours(W)];
+    err = max(abs(Y_gt-Y_ours))/H;
+
+    if PLOT
+        hold on
+        plot(X, Y_gt);
+    end
+
+    fprintf('----------------------------------------\n')
+    fprintf('File %i, error: %f\n', f, err);
+    fprintf('----------------------------------------\n')
+
+    all_errors(f) = err;
+end
+
+% compute AUC score for training  and testing set
+auc_train = calc_auc(all_errors(1:25));
+auc_test = calc_auc(all_errors(26:end));
+
+fprintf('AUCtrain: %2.4f. AUCtest:%2.4f\n', auc_train, auc_test);
+
+% should output something close to AUCtrain: 0.8940. AUCtest:0.8970
+
+toc