Smooth Contours =============== Version 1.0 - August 26, 2016 by Rafael Grompone von Gioi and Gregory Randall Introduction ------------ Smooth Contours is an unsupervised algorithm for detecting smooth contours on digital images. This code is part of the following IPOL article which describes the method: "Unsupervised Smooth Contour Detection" by Rafael Grompone von Gioi and Gregory Randall, Image Processing On Line, 2016. http://dx.doi.org/10.5201/ipol.2016.175 Files ----- README.txt - This file COPYING - GNU AFFERO GENERAL PUBLIC LICENSE Version 3 Makefile - Compilation instructions for 'make' smooth_contours.c - Smooth Contours module ANSI C89 code (peer reviewed) smooth_contours.h - Smooth Contours module ANSI C89 header (peer reviewed) smooth_contours_cmd.c - Command line interface for Smooth Contours, ANSI C89 io.c - Input/Output functions for command interface, ANSI C89 io.h - Input/Output functions header, ANSI C89 image.pgm - Test image in PGM format image.asc - Test image in ASC format image_out.txt - Expected result for the test 'image.pgm' as a TXT file image_out.pdf - Expected result for the test 'image.pgm' as a PDF file The files 'smooth_contours.c' and 'smooth_contours.h' were subject to peer review as part of the acceptance process of the IPOL article and are the official version of Smooth Contours. Compiling --------- Smooth Contours is an ANSI C89 language program and can be used as a module to be called from a C language program or as an independent command. In the distribution is included a Makefile file with instructions to build the command line program 'smooth_contours'. A C compiler must be installed on your system as well as the program 'make'. Smooth Contours only uses the standard C library so it should compile in any ANSI C89 Language environment. In particular, it should compile in a Unix like system. The compiling instruction is make from the directory where the source codes and the Makefile are located. If the compilation needs to be made manually, the usual command to do it is: cc -o smooth_contours smooth_contours_cmd.c io.c smooth_contours.c -lm To verify a correct compilation you can apply Smooth Contours to the test image 'image.pgm'. This can be done by executing: make test This produces the results 'output.txt' and 'output.pdf' which should be very similar to the provided results 'image_out.txt' and 'image_out.pdf'. There should be no difference other than the numerical error due to the use of different computer systems. Running the Command Line Interface ---------------------------------- The simplest Smooth Contours command execution is smooth_contours (use ./smooth_contours if the command is not included in the current path). That should print Smooth Contours version number and a description of the command line interface, including the available options. The input image formats handled are PGM (in its two versions, ASCII and Binary) and the ASC format (as defined by the CImg Library and as described below). A typical execution is: smooth_contours image.pgm -t output.txt That gives the result as a TXT file 'output.txt' which consists of two columns of real numbers in ASCII format (the numbers are separated by a space). Each row corresponds to a contour point, the first column gives the x coordinate and the second row gives the y coordinate. Contour points of consecutive rows are part of the same curve, they are chained. Each curve is ended by a row '-1 -1', which marks the end of the curve or chain. A new chain may start on the next row. The end of the file indicates that no more curves are present. For closed curves, the first point of the curve is repeated again as the last point of the chain. The following is an example of output: 9 5.57116 10 5.73102 11 6.64051 11.9352 8 12.0939 9 11.9844 10 11.4029 11 10 12.0179 9 12.119 8 11.9399 6.62612 11 5.65646 10 5.51349 9 5.62126 8 7 6.54667 8 5.68361 9 5.57116 -1 -1 2.09193 5 2.17282 4 3 2.7223 4 2.13559 5 1.99507 -1 -1 It corresponds to two curves, each one ended by a '-1 -1' row. The first one is a closed curve described by 16 points. Please note that the list has 17 points, but the first and last are the same, '9 5.57116', indicating a closed curve. The second curve is an open curve described by five points. (Note that one of the two coordinates is always an integer; this is due the particular implementation of the heuristics used to speed-up the algorithm.) For easy visualization of the result, the command line interface can also provide the output in PDF file format: smooth_contours image.pgm -p output.pdf This will produce the PDF file 'output.pdf'. Using both options will generate the TXT and PDF outputs: smooth_contours image.pgm -p output.pdf -t output.txt Note that the line width used in the PDF output is arbitrary. By using a smaller value, the sub-pixel accuracy of the result is better appreciated: smooth_contours image.pgm -p output.pdf -w 0.5 It can also be set to zero: smooth_contours image.pgm -p output.pdf -w 0 which means that the software rendering the PDF will choose the smallest possible line width that can be rendered in the current device. This is useful to see details but it is not recommended for figures to be distributed as the rendering is device dependent. The quantization step of pixel values has an impact on the result of Smooth Contours. With the usual image representation with integer pixels in [0,255] the quantization step should be 1. The same quantization step is valid for integer pixels over a larger range. However, due to the common use of image compression methods, quantization steps of 2 or more are often observed. To be conservative and prevent artifacts on compressed images, the default quantization step is set to 2. If the algorithm is used in different conditions, typically when applied to floating point images (in ASC format), the quantization step may need to be indicated. This can be done with the -q option: smooth_contours image.asc -q 1.0 -p output.pdf -t output.txt The last example set the quantization step to 1, a reasonable value for the test image 'image.asc' which has no compression artifacts; in different conditions, 1.0 should be replaced by the appropriate number. The ASC file format ------------------- The ASC image file format was defined by the CImg Library (http://cimg.eu/). It is a simple ASCII format allowing to store 4D arrays of floating point values (and not just integer as in PGM). In addition, multiple channels and multiple frames are possible; the command line interface of Smooth Contours, however, only handles a single gray level frame. The main reason to include this file format is to be able to use floating point images in a simple way. As an example, the file 'image.asc' included in this distribution contains the same image as 'image.pgm' but in ASC file format. To explain the ASC file format, the following is an example of a 6x6 floating point gray-level in ASC format: 6 6 1 1 0.0022 0.1119 0.9455 1.7084 0.9455 0.1119 0.1119 1.7270 5.8871 7.4892 5.8871 1.7270 0.9455 5.8871 9.6757 9.9586 9.6757 5.8888 1.7084 7.4892 9.9586 9.9999 9.9586 7.4934 0.9455 5.8871 9.6757 9.9586 9.6757 5.8888 0.1119 1.7270 5.8888 7.4934 5.8888 1.7271 An ASC file consists of a simple header followed by the data, all written as numbers in ASCII format. The header is just four integer numbers separated by spaces and ending in a new line. The four numbers of the header correspond to the size of each of the 4 dimensions X, Y, Z and C (in that order). X is the width of the image; Y is the height of the image; Z is the number of frames; C is the number of channels. For single a frame and a single channel (as in the example above and as required by Smooth Contours), Z=1 and C=1. The header is followed by the data written in standard ASCII floating point notation. Any format accepted by the standard C function scanf is valid; for example: 0, 255, 692315, 0.34230295282, -30.3423, +45, 1e10, 5E4, 3.14e-34. The numbers are separated by any combination of spaces, tabs, or end-of-line. The order of the numbers is important. The pixels have coordinates (x,y,z,c), with 0 <= x < X and 0 <= y < Y and 0 <= z < Z and 0 <= c < C. The pixel (x,y,z,c) will be stored at position x + y*X + z*X*Y + c*X*Y*Z. Thus, the first number following the header corresponds to pixel (0,0,0,0) which is the upper left pixel of the first channel of the first frame. The second value is the second pixel on the same row (1,0,0,0) and the following values complete the first row up to (X-1,0,0,0). Then comes the second row of the first channel of the first frame, from (0,1,0,0) to (X-1,1,0,0). Then the following rows and so on until the last row of the frame, (0,Y-1,0,0) to (X-1,Y-1,0,0). This would complete the image if only one frame and one channel are present (as required in Smooth Contours and as in the example above). In multiple frame and multiple channel (Z>1 and/or C>1), the next values will store, in the same way, the first channel of the second frame. When all the frames are complete, the same procedure will be done for the values of the second channel, and so on. Copyright and License --------------------- Copyright (c) 2016 Rafael Grompone von Gioi and Gregory Randall Smooth Contours 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. Smooth Contours 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 . Thanks ------ We would be grateful to receive any comment, especially about errors, bugs, or strange results.