ImageRec is a simple and lightweight computer vision tool for small Linux based embedded systems like the very cheap MT7688AN SoC. I developed the tool for camera based feedback control without a PC or a powerful ARM based system. This was a requirierend for an analytical instrument to control droplet sizes. The tool can capture images from v4l2 camera devices (most usb webcams) and recognizes lines and circles using Hough transformation.

The tool can be used by command line to capture single frames and carry out image analysis or it can open a tcp/ip-port for receiving commands and returning the results. It is designed to be used from local running scripts (e.g. micro python or bash) or remotely from a PC for debugging purposes. Netcat can be very convenient for testing. ImageRec uses only fixed point operations and is optimized for a low memory footprint.

The Hough transformation for lines returns the intersection point of the detectet line with an ortogonal line crossing the image center. For circles the Hough Transformation returns the center of the detected circle. The meniscus Hough transformation returns the point with the smalest x position on the detected circular segment. By using the store and recall function different Hough transformations can be executed without capturing a seperate image from the camera device.

Beside pixel positions it can return 3x3 pixel clusters to allow position calculation of a recognized shape with sub-pixel precision.


To find the position of circles the following procedure usually works best:

imagerec -d /dev/video0 -r 640*480 -c cgnexCngml

"c" for capturing an image from the camera;

"g" for apply a Gaussian filter. For noisy images it may help to call it multiple times;

Gausian filtered image of a droplet
Gausian filtered image of a droplet

"n" to normalize the image. Because of fixed point calculations this can be very important;

"e" to apply a convolution with the Sobel operator. It calculates the derivative of the image brightness in x and y direction separately. (therefore two image buffers with the full image resolution are generated);

Derivative of the image brightness in y direction
Derivative of the image brightness in y direction

"x" remove all pixels in the two buffers which seems not to be part of a continues edge;

Remaining continues edges
Remaining continues edges

"C" apply Hough transformation to the image by taking the directional slope into account;

Result of Hough transformation
Result of Hough transformation

"n" to normalize the image again.

"g" for apply a Gaussian filter.

Gausian filtered result of the Hough transformation
Gausian filtered result of the Hough transformation

"m" remove all pixel that do not belong to a local maximum. Therefore, only one pixel at each "mountain top" will remain.

Remaining maximum pixels marked with red circle
Remaining maximum pixels marked with red circleOriginal image with annotation of the detected circle
Original image with annotation of the detected circle

"l" outputs a list with the positions of all these pixels sorted by brightness.


Output of imagerec -h

Usage: imagerec [-options]
        -h                show help
        -c commands        ASCII command string
        -p port            TCP/IP-port to listen on
        -d device          capture device name
        -r whidth*hight    image resolution
        -n pixels          max number of pixels for l command
        -f file            file path for w command (# for index)
        -s                silent mode – outputs results only

examples: imagerec -d /dev/video0 -r 640*480 -p 5044
          imagerec -d /dev/video0 -r 640*480 -c cgnexCngml
          imagerec -d /dev/video0 -r 640*480 -c cgnexCnw -f result.tif
          imagerec -d /dev/video0 -r 640*480 -c cgnwexsonwrCnw -f result#.tif

single byte ASCII commands:
          c    capture image
          n    normalize image
          g    apply Gausian blur
          e    edge detection with Sobel filter, must be
                folowd by 'x', 'o' or a hough transformation
          x    remove non edge pixel, must be folowd by
                'o' or a Hough transformation
          o    convert directional slope to absolute slope
          C    circle Hough transformation
          L    line Hough transformation
          H    line Hough transformation (horizontal only)
          V    line Hough transformation (vertical only)
          M    meniscus Hough transformation
          b    binarize
          m    remove non-local-maxima pixels
          l    list brightes pixels (from max. 32 non black pixels)
          p    list brightes pixel clusters (3x3)
          q    close connection
          s    store a copy of the current buffer
          r    recall a copy of the stored buffer
          w    write buffer to disk (TIF format)
          z    set index for output file name to zero
          d    show result data only
          i    show info and result data (default)

example: echo \"cngexCngmlq\" | nc localhost 5044


The code is open source and published on GitHub: