/EcoAN

It's a tool to make image annotations simple.

Primary LanguageMATLABGNU General Public License v3.0GPL-3.0

This software is designed to annotate images with boxes.  It keeps the
annotations in text files with the same image file name and a ".ann" extension.

Characteristics:
* It's all coded in matlab.  I tested with matlab 2009, not really sure what the
  requirements are with other matlab releases.  If you have a problem, just drop
  me a mail <joel.granados@gmail.com >

* All the development and testing has been done in linux (fedora 13).

List of features:
1. Zoom: The zoom button turns on/off the zoom state.  Once in zoom state you
   can zoom-in and zoom-out of the image that is located in the main window.  To
   zoom in you can double-click the image; this will zoom into the part you
   clicked.  When in the zoom state you can also specify a zoom zone with a
   square.  The application will make the selected square of the size of the
   main window.  Finally if you have a mouse with a middle wheel, this will zoom
   in/out.

2. Grab: When you are zoomed in an image you might want to move around to see
   adjacent sections.  This is made possible by the grab functionality.  When
   you push the grab button you enter the Grab state.  When in Grab state you
   can grab the image and move it to other adjacent sections.  Note that the
   grab is only relevant when you are zoomed in the image.

3. Correct: Annotation can be wrong.  The correct button is designed to enter a
   Correction state.  In this state the user can correct the existing
   annotations.  In the Correction state you can select existing annotations by
   clicking on their boarders.  When selected you can change the label or you
   can erase it altogether by pressing "d".

4. Review: The review panel goes hand in hand with the Correction state.  It is
   used to keep track of the person doing the corrections.  To activate the
   review feature you must press the checkbox named Review Mode.  You must also
   place you name in the Reviewer text area.  The date is placed automatically.
   The reviewer information will be kept together with the rest of annotation
   info.

5. Add Files: This button allows you to search for the pictures.  You should use
   this button to search for pictures in the local machine.

6. File List: This is a list of all the files that you selected to be annotated.
   When you click on a file in the list, the previous file annotation will be
   saved and the new image will be displayed.  Note that this is the way to save
   the annotations.  There is no annotation button.

7. Exit: Button to exit.

8. Color spaces: There is a paner on the lower right side of the window that
   contains some known color spaces and other transformations.  Just click on
   the radio button of your choice and see the image transformed.  If the image
   is "big" it might take a bit to do the transformation.

Suggested workflows:
1. Starting the application:
    To start you need to initialize matlab.  After you are in the matlab
    console, you must look for the directory where you have placed the
    annotation files.  Search for the file named annotation_gui.m and "run" the
    file.  To run the file you can right-click and select "run".
    For those of you that realize that this is a bit too much work, you can use
    the -r matlab argument to make an icon or an alias.  Let's assume that my
    annotation files are located at "/tmp/annotation" directory.  I can execute
    the following command to go directly to the application: `matlab -r "cd
    /tmp/annotation ; annotation_gui"`.  You can also use that line to create an
    alias or an icon.
    To see useful labels, you must create a labels.txt file in the directory
    where the images are located.  This file will contain a label per line.  You
    should leave this file in the image directory so it is read every time the
    images are accessed.

2 Creating an annotation:
    a. Be sure that you are not in Zoom, Grab or Correct mode.
    b. Make sure that the label contains the string that you will use for the
       annotation. (You can change the contents of the label by clicking the
       arrow at the far right).
    c. Place the cursor where you want to start the annotation square.
    d. Click and hold the click while you drag the square to the end position.
    e. When you are satisfied with the result let go of the click and a square
       should appear with the selected label.
    f. If you want to modify the annotation square or the annotation label you
       should use the left-click.  When you left-click and hold  in the
       vicinity of the newly created square you can resize it as you please.
       Notice that changes in the label will also be visible when you left-click
       near the newly created square.

3. Finding something interesting: When your target objects are small you must
   use the zoom/grab feature
    a. Look at the picture from afar and zoom into points of interest.  Points
       where you suspect that you might find something interesting.
    b. You can change from the zoom state to the grab state and move around the
       place of interest.
    c. After you are convinced that you have thoroughly searched a specific
       zone, zoom out and repeat a and b.

4. Correcting
    a. Before you start correcting remember to activate the Review Mode and put
       your name on the text area.  Try to be consistent with the way you type
       in your name.
    b. Try to go through the images in the order they appear in the File List.
    c. If you see that the square is correct and you need only to change the
       label, select the square (it should turn green) and then change the label
       in the label list.
    d. If you see that the whole annotation is incorrect, you can delete the
       selected square (It should be green), by pressing "d".  Afterwards, you
       will have to create a new annotation all together.

Possible Problems:
* "d" scrolls the label list instead of deleting:  When I selected a square for
    correction, changed the label with the mouse and finally tried to delete it
    by pressing "d"; this would cause the label list to advance.  To get out of
    this situation just select the square of interest with the mouse once more.