home > kero > Documentation

Given a folder of images and a tag folder containing the same images, each of which is marked with white color, RGB=(255,255,255), this function creates

  1. a clone of the folder,
  2. a folder of its ground truth images based on the tag folder,
  3. a folder containing the images in the folder with bounding boxes based on the ground truth images along with text files containing
    image_label img-width img-height xmin ymin xmax ymax
    where (xmin,ymin) the top-left coordinates of the bounding box and (xmax,ymax) bottom-right bounding box.

Tips. Consider using clone_to_annotate_faster().

def clone_to_annotate(self,this_folder, tag_folder,starting_label,annotation_name,


this_folder String. The name of the folder with images.
tag_folder String. The name of the folder with images. If each image in the tag_folder has a corresponding image of the same name and type, then clone folder, clone tag folder, ground truth image folder and annotation folder will be created with their corresponding contents.
starting_label Integer. The sequence of numbers will start with this integer.
annotation_name String. The image label for the white region marked in the tag folder. This will be saved in annotation .txt files.

In example 1, this is “butterfly”. This means that we label the object marked with white a “butterfly”.

order_name String. The clone of this_folder will be relabelled with prefix specified by this string.

Default value =”img”

tag_name String. The clone of tag_folder will be relabelled with prefix specified by this string.

Default value =”imggt”

check_missing_mode Boolean. If True, cloning process of the folders are not performed. The file names of images in this_folder that do not have the corresponding images in the tag_folder will be printed.

Default value =False

rotate_angle_set List of float. Each float is a value in degree with which an image is rotated.

Default value =None

skip_ground_truth Boolean. Set to True if the ground truth images have been created in the manner spawn_ground_truth() spawns them. The function will continue with annotations.
significant_fraction Float. This argument takes in values between 0 and 1.0. It specifies the fraction of area relative to the area of whole matrix, above which a component will be considered as a component. Smaller than this value, the component will be treated as noise. This is an argument to the function get_connected_components().

Default value = .001

thresh Integer, from 0 to 255. This specifies the RGB values below which the ground truth color is treated converted to black, RGB=(0,0,0) and otherwise white, RGB=(255,255,255).

For example, if the value is set to 244, a pixel with (255,254,246) is converted to white since 244<255,254 and 246 while a pixel with (20,40,120) is converted to black.

Default value = 254

scale “Auto”, (Integer,Integer) or None. Annotation of images are computed from down-scaled images to improve the processing speed (unless scale=None). If set to “Auto”, the image will be downsized to (200,150) for processing.

This is an argument to the function multiple_scaled_box_positions().

Default value = “Auto”

Note: The actual image is not changed, only that the annotation positions are re-computed back from down-scaled images, giving potential loss of accuracy.

Tips: If annotation fails for one reason or another after ground truth image generation is complete, then make sure to set skip_ground_truth=True before rerunning the function, so that we do not waste time re-spawning the ground truth images.

Tips: For images whose objects are very small, setting a small scale might be a bad choice, since the position of annotation boxes might loss a lot of accuracy during rescaling.

Example usage 1.

Download the example here and put them in the working directory under the folder /bb.

import kero.ImageProcessing.photoBox as kip

this_folder = "bb\\Butterflies"
tag_folder =  "bb\\Butterflies_canvas"

rotate_angle_set = [0,30,60,90,120,150,180] # None
annotation_name = "butterfly"
gsw.clone_to_annotate(this_folder, tag_folder,1,annotation_name, check_missing_mode=False,rotate_angle_set=rotate_angle_set)

This function will call spawn_ground_truth(), i.e. create ground truth image (figure 1 top-right) of the image (figure 1 top-left) based on the corresponding image from tag folder (figure 1 top-center), and furthermore create annotations for each images. Samples of images from the folders are shown below.


Figure 1.

A folder containing rotated figures (figure 2) will be created. Also, a txt file will be created for each rotated copy of the image. The bounding boxes are the thin green rectangles.


Figure 2.

kero version: 0.4.2 and above