lblconv

package module
v0.0.0-...-f32be47 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 20, 2019 License: MIT Imports: 26 Imported by: 0

README

lblconv

lblconv can convert labels between different label formats, with a focus on rectangular bounding boxes for object detection tasks in computer vision and related image based machine learning contexts. It supports various filtering and transformation functions for the annotations themselves and the images they refer to.

Supported formats:

  • AWS Rekognition detect-labels (read only)
  • AWS Rekognition detect-text (read only)
  • KITTI 2D object detection (read/write)
  • Sloth (read/write)
  • TensorFlow TFRecord (write only)
  • VGG Image Annotator (VIA) (read/write)

Note that not all attributes supported by these formats are retained during the conversion.

Getting Started

Installing

With Go (Golang) installed on your machine, run the following command to download, build and install the tool:

go get -u github.com/sensorable/lblconv/cmd/lblconv
Usage

The same format can be set as the source and target if both reading and writing are supported for the given format and the intention is to merely filter or transform the data rather than convert between formats.

Usage: lblconv -from <format> -to <format> [<arg> ...]

The supported input (-from) and output (-to) formats and their required arguments:
  AWS Rekognition detect-labels:
    -from aws-dl -labels <dir> -images <dir>
  AWS Rekognition detect-text:
    -from aws-dt -labels <dir> -images <dir>
  KITTI 2D object detection:
    -from kitti -labels <dir> -images <dir>
    -to kitti -labels-out <dir>
  Sloth:
    -from sloth -labels <file>
    -to sloth -labels-out <file>
  TensorFlow TFRecord:
    -to tfrecord -labels-out <file> -tfrecord-label-map-file <file> [-num-shards <int>]
  VGG Image Annotator (VIA):
    -from via -labels <file>
    -to via -labels-out <file>

Arguments:
  -bbox-aspect-ratio ratio
        The output aspect ratio for object bounding boxes; bounding boxes are grown (not shrunk) to match this ratio when it is > 0
  -bbox-scale-x float
        A scale factor for the width of all bounding boxes (default 1)
  -bbox-scale-y float
        A scale factor for the height of all bounding boxes (default 1)
  -crop-objects
        Crop and output objects from images (image processing flags apply to the individual crops)
  -downsample-filter string
        The filter to use when downsampling an image {nearest, box, linear, gaussian, lanczos} (default "box")
  -filter-attributes string
        Comma-separated list of attributes to keep (if the target format supports attributes; empty string keeps all)
  -filter-labels string
        Comma-separated list of labels to keep (after map-labels; empty string keeps all)
  -filter-required-attrs string
        Comma-separated list of required attributes whose values must not be the Go zero value for their type to keep the annotation
  -from format
        The source format
  -image-enc encoding
        The encoding for output images {jpg, png} (default "jpg")
  -images path
        The path to the image input directory
  -images-out path
        The path to the image output directory (only required when image processing functionality is used
  -jpeg-quality int
        The quality to use when encoding JPEGs [1, 100] (default 90)
  -labels path
        The path to the label input file (sloth, via) or directory (kitti, aws-dl, aws-dt)
  -labels-out path[,...]
        The comma-separated paths (path[,...]) to the label output files (sloth, tfrecord, via) or directories (kitti); must be one path per value in flag -split
  -map-labels string
        Comma-separated list of old=new label (sub-)string replacements
  -max-bbox-aspect-ratio ratio
        The max. required aspect ratio (width/height) for object bounding boxes (before resizing; zero disables the filter)
  -min-bbox-aspect-ratio ratio
        The min. required aspect ratio (width/height) for object bounding boxes (before resizing; zero disables the filter)
  -min-bbox-height pixels
        The min. required height in pixels for object bounding boxes (before resizing)
  -min-bbox-width pixels
        The min. required width in pixels for object bounding boxes (before resizing)
  -min-confidence float
        The minimum confidence value to keep a label; range [0.0, 1.0)
  -num-shards int
        The number of shard files to create (tfrecord only) (default 1)
  -require-label
        Require at least one label (after filters) to keep the file
  -resize-longer length
        The target length for the longer side of the image (zero to keep aspect ratio)
  -resize-shorter length
        The target length for the shorter side of the image (zero to keep aspect ratio)
  -split percent[,...]
        The comma-separated output split percentages (percent[,...]) to divide labels into (only sloth, tfrecord, and via output formats); must add up to 100% (default "100")
  -tfrecord-label-map-file path
        The TFRecord label map file path
  -to format
        The target format
  -upsample-filter string
        The filter to use when upsampling an image {nearest, box, linear, gaussian, lanczos} (default "linear")

Documentation

Overview

Package lblconv implements functionality to parse a number of supported label formats, process and transform the label metadata and corresponding images, and output the serialised results in the same or a a different format.

Index

Constants

View Source 
const (
	AncestorLabels = "Ancestors"  // Ancestors in the label taxonomy. Type []string.
	Confidence     = "Confidence" // Type float64 in [0.0, 1.0].
	CropCoords     = "CropCoords" // Absolute coords (x1,y1)(x2,y2) in the source image. Type string.
	DetectedText   = "Text"       // Text that is associated with the bounding box. Type string.
)

Keys for known annotation attributes.

Variables

This section is empty.

Functions

func WriteCustomTFRecord 

func WriteCustomTFRecord(recordFilePath, labelMapPath string, data []AnnotatedFile,
	numShards int, customiseFeature func(f AnnotatedFile, m TFFeatureMap)) (err error)

WriteCustomTFRecord works like WriteTFRecord, except that it allows for the TFFeatureMap to be customised.

Before generating a tensorflow.Example from each AnnotatedFile and writing it to the TFRecord file, the source data and TFFeatureMap containing the default conversion for object records are passed to customiseFeature, which may modify the feature map to its liking, as long as all of its values can be converted to tensorflow.Feature.

func WriteKitti 

func WriteKitti(dirPath string, data []KITTIAnnotatedFile) error

WriteKitti writes data to dirPath, one file per element.

func WriteSloth 

func WriteSloth(outFile string, data []SlothAnnotatedFile) error

WriteSloth writes the Sloth annotations to outFile.

func WriteTFRecord 

func WriteTFRecord(recordFilePath, labelMapPath string, data []AnnotatedFile, numShards int) error

WriteTFRecord does a streaming conversion, serialisation and file write for the annotation data to one or more TFRecord files stored under recordFilePath (with suffixes added when numShards>1).

A label map is generated and written to labelMapPath.

func WriteVIA 

func WriteVIA(outFile string, data VIAProject) error

WriteVIA writes the VIA project data to outFile.

Types

type AWSBoundingBox 

type AWSBoundingBox struct {
	Left   float64
	Top    float64
	Width  float64
	Height float64
}

AWSBoundingBox defines an axis-aligned rectangle with the dimensions given as normalised ratios of the image size.

type AWSDLAnnotatedFile 

type AWSDLAnnotatedFile struct {
	Annotations  []AWSLabel `json:"Labels"`
	FilePath     string     `json:"-"`
	ModelVersion string     `json:"LabelModelVersion"`
}

AWSDLAnnotatedFile defines the AWS detect-labels annotation structure for a single file.

type AWSDTAnnotatedFile 

type AWSDTAnnotatedFile struct {
	Annotations []AWSTextDetection `json:"TextDetections"`
	FilePath    string             `json:"-"`
}

AWSDTAnnotatedFile defines the AWS text detection annotation structure for a single file.

type AWSGeometry 

type AWSGeometry struct {
	BoundingBox AWSBoundingBox
	Polygon     []AWSPoint
}

AWSGeometry is the geometry of a text object annotation.

type AWSInstance 

type AWSInstance struct {
	BoundingBox AWSBoundingBox
	Confidence  float64 // Range [0, 100].
}

AWSInstance is an object instance in an AWS label.

type AWSLabel 

type AWSLabel struct {
	Confidence float64 // Range [0, 100].
	Instances  []AWSInstance
	Name       string
	Parents    []struct {
		Name string
	}
}

AWSLabel is a single annotation within an AWS labels file.

type AWSPoint 

type AWSPoint struct {
	X float64
	Y float64
}

AWSPoint defines a point in an image. The coordinates are normalised ratios of the image size.

type AWSTextDetection 

type AWSTextDetection struct {
	Confidence   float64 // Range [0, 100].
	DetectedText string
	Geometry     AWSGeometry
	ID           int
	ParentID     *int   // Nil when Type=="LINE".
	Type         string // LINE or WORD.
}

AWSTextDetection is a single text annotation within an AWS detect-text label file.

type AnnotatedFile 

type AnnotatedFile struct {
	Annotations []Annotation // The annotations.
	FilePath    string       // The annotated file.
}

AnnotatedFile is the intermediate representation of file metadata.

func FromAWSDetectLabels 

func FromAWSDetectLabels(labelDir, imageDir string) ([]AnnotatedFile, error)

FromAWSDetectLabels reads and parses AWS detect-labels annotations from labelDir and matches them to the images in imageDir.

func FromAWSDetectText 

func FromAWSDetectText(labelDir, imageDir string) ([]AnnotatedFile, error)

FromAWSDetectText reads and parses AWS detect-text annotations from labelDir and matches them to the images in imageDir.

func FromKitti 

func FromKitti(labelDir, imageDir string) ([]AnnotatedFile, error)

FromKitti reads and parses KITTI annotations from labelDir and matches them to the images in imageDir.

func FromSloth 

func FromSloth(path string) ([]AnnotatedFile, error)

FromSloth reads and parses Sloth annotations from the file at path.

func FromVIA 

func FromVIA(path string) ([]AnnotatedFile, error)

FromVIA reads and parses VIA annotations from the file at path.

type AnnotatedFiles 

type AnnotatedFiles []AnnotatedFile

AnnotatedFiles is the annotation metadata for a list of files.

func (*AnnotatedFiles) Filter 

func (data *AnnotatedFiles) Filter(labelNames, attributes, requiredAttrs []string,
	minConfidence float64, requireLabel bool, minBboxWidth, minBboxHeight, minAspectRatio,
	maxAspectRatio float64)

Filter filters out annotations which do not match any of the given labelNames, have a confidence value less than minConfidence, a bounding box with less than minBboxWidth or minBboxHeight, or do not match the required aspect ratio.

The aspect ratio of width/height must be in [minAspectRatio, maxAspectRatio], except that a min/max value of zero disables the respective filter.

If attributes is non empty, only the listed attributes are kept. This only filters the list of attributes, not the annotations themselve.

Similarly, requiredAttrs specifies attributes that must be present with a value that is not the Go zero value of their type. If this test fails for an annotation, that annotation is deleted.

func (*AnnotatedFiles) MapLabels 

func (data *AnnotatedFiles) MapLabels(mappings []string) error

MapLabels replaces label (sub-)strings with substitution values, as specified in mappings.

The format of mappings is old=new.

func (*AnnotatedFiles) ProcessImages 

func (data *AnnotatedFiles) ProcessImages(imageOutDir string, longerSide, shorterSide int,
	downsamplingFilter, upsamplingFilter, encoding string, jpegQuality int,
	doCropObjects bool) error

ProcessImages resizes all referenced images and writes them to imageOutDir using the specified encoding.

If doCropObjects is true, individual objects as per the labels are cropped from the images. The crops are resized instead of the original images in this case. The data changes accordingly, with 0 or more cropped images replacing the original AnnotatedFile.

func (*AnnotatedFiles) Split 

func (data *AnnotatedFiles) Split(cumulativeSplits []int) ([]AnnotatedFiles, error)

Split randomly splits the data into multiple datasets.

The cumulativeSplits specify the cumulative distribution according to which the data is split into the returned datasets. Its values must add up to 100!

func (*AnnotatedFiles) TransformBboxes 

func (data *AnnotatedFiles) TransformBboxes(scaleX, scaleY, aspectRatio float64)

TransformBboxes transforms bounding boxes.

First bboxes are scaled by the horizontal and vertical scale factors scaleX and scaleY.

Next, the bounding box is grown (never shrunk) to match the desired aspect ratio. An aspectRatio of zero disables this transformation.

type Annotation 

type Annotation struct {
	Attributes map[string]interface{} // Additional attributes of this annotation.
	Coords     [4]float64             // Absolute x1, y1, x2, y2 offsets from the top-left corner.
	Label      string
}

Annotation is the intermediate representation of an object label.

func (Annotation) Height 

func (a Annotation) Height() float64

Height is the object height from a.Coords.

func (Annotation) Width 

func (a Annotation) Width() float64

Width is the object width from a.Coords.

type KITTIAnnotatedFile 

type KITTIAnnotatedFile struct {
	Annotations []KITTIAnnotation
	FilePath    string
}

KITTIAnnotatedFile defines the KITTI annotation structure for a single file.

func ToKitti 

func ToKitti(data []AnnotatedFile) []KITTIAnnotatedFile

ToKitti converts the intermediate representation to KITTI format.

type KITTIAnnotation 

type KITTIAnnotation struct {
	Coords [4]float64 // x1, y1, x2, y2
	Label  string
	Score  float64 // Optional, linear confidence value. No fixed range.
}

KITTIAnnotation is a single annotation within a KITTI file.

type SlothAnnotatedFile 

type SlothAnnotatedFile struct {
	Annotations []SlothAnnotation `json:"annotations"`
	Class       string            `json:"class,omitempty"`
	FilePath    string            `json:"filename,omitempty"`
}

SlothAnnotatedFile defines the Sloth annotation structure for a single file.

func ToSloth 

func ToSloth(data []AnnotatedFile) []SlothAnnotatedFile

ToSloth converts the intermediate representation to Sloth format.

type SlothAnnotation 

type SlothAnnotation struct {
	Class  string  `json:"class,omitempty"`
	Type   string  `json:"type,omitempty"`
	X      float64 `json:"x,omitempty"`
	Y      float64 `json:"y,omitempty"`
	Width  float64 `json:"width,omitempty"`
	Height float64 `json:"height,omitempty"`
}

SlothAnnotation is a single annotation within a Sloth file.

type TFFeatureMap 

type TFFeatureMap map[string]interface{}

TFFeatureMap maps feature names to their values. Values must be convertible to tensorflow.Feature.

type TFRecordAnnotatedFile 

type TFRecordAnnotatedFile struct {
	Annotations TFFeatureMap
	FilePath    string
}

TFRecordAnnotatedFile defines the TFRecord annotation structure for a single file.

type VIAAnnotatedFile 

type VIAAnnotatedFile struct {
	Annotations []VIARegionAnnotation `json:"regions"`
	Attributes  map[string]string     `json:"file_attributes"`
	FilePath    string                `json:"filename"`
	Size        int64                 `json:"size"`
}

VIAAnnotatedFile defines the VIA annotation structure for a single file.

type VIAAttributes 

type VIAAttributes struct {
	Region map[string]interface{} `json:"region"`
	File   map[string]interface{} `json:"file"`
}

VIAAttributes defines the VIA attribute metadata.

type VIAOptionsAttribute 

type VIAOptionsAttribute struct {
	Type           string            `json:"type"` // "radio" or "dropdown"
	Description    string            `json:"description"`
	Options        map[string]string `json:"options"`
	DefaultOptions map[string]bool   `json:"default_options"`
}

VIAOptionsAttribute defines attributes of type "radio" or "dropdown".

type VIAProject 

type VIAProject struct {
	Attributes    VIAAttributes               `json:"_via_attributes"`
	ImageMetadata map[string]VIAAnnotatedFile `json:"_via_img_metadata"`
	// Must exist for VIA to load the project. Default values will be used.
	Settings struct{} `json:"_via_settings"`
}

VIAProject defines the VIA project structure.

func ToVIA 

func ToVIA(irData []AnnotatedFile) VIAProject

ToVIA converts the intermediate representation to VIA format.

type VIARegionAnnotation 

type VIARegionAnnotation struct {
	Attributes map[string]string `json:"region_attributes"`
	Shape      VIAShape          `json:"shape_attributes"`
}

VIARegionAnnotation is a single region annotation for a particular image in a VIA file.

type VIAShape 

type VIAShape struct {
	Name   string `json:"name"`
	X      int32  `json:"x"`
	Y      int32  `json:"y"`
	Width  int32  `json:"width"`
	Height int32  `json:"height"`
}

VIAShape describes the shape of an annotation.

type VIATextAttribute 

type VIATextAttribute struct {
	Type         string `json:"type"` // "text"
	Description  string `json:"description"`
	DefaultValue string `json:"default_value"`
}

VIATextAttribute defines attributes of type "text".

Source Files

View all Source files

Directories

Path Synopsis
cmd
lblconv
Converts between KITTI, Sloth, AWS detect-labels, AWS detect-text, TFRecord and VGG Image Annotator label formats.
 Converts between KITTI, Sloth, AWS detect-labels, AWS detect-text, TFRecord and VGG Image Annotator label formats.
third-party
github.com/ryszard/tfutils/go/example
package example gives you some syntactic sugar to build tensorflow.Example protobufs in a more intuitive way.
 package example gives you some syntactic sugar to build tensorflow.Example protobufs in a more intuitive way.
github.com/ryszard/tfutils/go/tfrecord
Package tfrecords provides facilities for reading and writing TFRecords files.
 Package tfrecords provides facilities for reading and writing TFRecords files.
github.com/ryszard/tfutils/proto/tensorflow/core/example
Package tensorflow is a generated protocol buffer package.
 Package tensorflow is a generated protocol buffer package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.