pigeon

README

Pigeon - Google Cloud Vision API on Golang

pigeon is a service for the Google Cloud Vision API on Golang.

Prerequisite

You need to export a service account json file to GOOGLE_APPLICATION_CREDENTIALS variable.

$ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service_account.json

To generate the credentials file, please, refer to this documentation page

Installation

pigeon provides the command-line tools.

$ go get github.com/kaneshin/pigeon/cmd/...

Make sure that pigeon was installed correctly:

$ pigeon -h

Usage

pigeon command

pigeon is available to submit request with external image source (i.e. Google Cloud Storage image location).

# Default Detection is LabelDetection.
$ pigeon assets/lenna.jpg
$ pigeon -face gs://bucket_name/lenna.jpg
$ pigeon -label https://httpbin.org/image/jpeg

pigeon package

import "github.com/kaneshin/pigeon"
import "github.com/kaneshin/pigeon/credentials"

func main() {
	// Initialize vision service by a credentials json.
	creds := credentials.NewApplicationCredentials("credentials.json")

	// creds will set a pointer of credentials object using env value of
	// "GOOGLE_APPLICATION_CREDENTIALS" if pass empty string to argument.
	// creds := credentials.NewApplicationCredentials("")

	config := pigeon.NewConfig().WithCredentials(creds)

	client, err := pigeon.New(config)
	if err != nil {
		panic(err)
	}

	// To call multiple image annotation requests.
	feature := pigeon.NewFeature(pigeon.LabelDetection)
	batch, err := client.NewBatchAnnotateImageRequest([]string{"lenna.jpg"}, feature)
	if err != nil {
		panic(err)
	}

	// Execute the "vision.images.annotate".
	res, err := client.ImagesService().Annotate(batch).Do()
	if err != nil {
		panic(err)
	}

	// Marshal annotations from responses
	body, _ := json.MarshalIndent(res.Responses, "", "  ")
	fmt.Println(string(body))
}

pigeon.Client

The pigeon.Client is wrapper of the vision.Service.

// Initialize vision client by a credentials json.
creds := credentials.NewApplicationCredentials("credentials.json")
client, err := pigeon.New(creds)
if err != nil {
	panic(err)
}

vision.Feature

vision.Feature will be applied to vision.AnnotateImageRequest.

// DetectionType returns a value of detection type.
func DetectionType(d int) string {
	switch d {
	case TypeUnspecified:
		return "TYPE_UNSPECIFIED"
	case FaceDetection:
		return "FACE_DETECTION"
	case LandmarkDetection:
		return "LANDMARK_DETECTION"
	case LogoDetection:
		return "LOGO_DETECTION"
	case LabelDetection:
		return "LABEL_DETECTION"
	case TextDetection:
		return "TEXT_DETECTION"
	case SafeSearchDetection:
		return "SAFE_SEARCH_DETECTION"
	case ImageProperties:
		return "IMAGE_PROPERTIES"
	}
	return ""
}

// Choose detection types
features := []*vision.Feature{
	pigeon.NewFeature(pigeon.FaceDetection),
	pigeon.NewFeature(pigeon.LabelDetection),
	pigeon.NewFeature(pigeon.ImageProperties),
}

vision.AnnotateImageRequest

vision.AnnotateImageRequest needs to set the uri of the form "gs://bucket_name/foo.png" or byte content of image.

• Google Cloud Storage

src := "gs://bucket_name/lenna.jpg"
req, err := pigeon.NewAnnotateImageSourceRequest(src, features...)
if err != nil {
	panic(err)
}

• Base64 Encoded String

b, err := ioutil.ReadFile(filename)
if err != nil {
	panic(err)
}
req, err = pigeon.NewAnnotateImageContentRequest(b, features...)
if err != nil {
	panic(err)
}

Submit the request to the Google Cloud Vision API

// To call multiple image annotation requests.
batch, err := client.NewBatchAnnotateImageRequest(list, features()...)
if err != nil {
	panic(err)
}

// Execute the "vision.images.annotate".
res, err := client.ImagesService().Annotate(batch).Do()
if err != nil {
	panic(err)
}

Example

Pigeon

input

$ pigeon -label assets/pigeon.png

output

[
  {
    "labelAnnotations": [
      {
        "description": "bird",
        "mid": "/m/015p6",
        "score": 0.825656
      },
      {
        "description": "anatidae",
        "mid": "/m/01c_0l",
        "score": 0.58264238
      }
    ]
  }
]

Lenna

input

$ pigeon -safe-search assets/lenna.jpg

output

[
  {
    "safeSearchAnnotation": {
      "adult": "POSSIBLE",
      "medical": "UNLIKELY",
      "spoof": "VERY_UNLIKELY",
      "violence": "VERY_UNLIKELY"
    }
  }
]

License

The MIT License (MIT)

Author

Shintaro Kaneko kaneshin0120@gmail.com

Documentation

Index

• Constants
• func DetectionType(d int) string
• func NewAnnotateImageContent(body []byte) *vision.Image
• func NewAnnotateImageContentRequest(body []byte, features ...*vision.Feature) (*vision.AnnotateImageRequest, error)
• func NewAnnotateImageSource(source string) *vision.Image
• func NewAnnotateImageSourceRequest(source string, features ...*vision.Feature) (*vision.AnnotateImageRequest, error)
• func NewFeature(d int) *vision.Feature
• type Client
  • func New(c *Config, httpClient ...*http.Client) (*Client, error)
  • func (c Client) ImagesService() *vision.ImagesService
  • func (c Client) NewAnnotateImageRequest(v interface{}, features ...*vision.Feature) (*vision.AnnotateImageRequest, error)
  • func (c Client) NewBatchAnnotateImageRequest(list []string, features ...*vision.Feature) (*vision.BatchAnnotateImagesRequest, error)
• type Config
  • func NewConfig() *Config
  • func (c *Config) WithCredentials(creds *credentials.Credentials) *Config
  • func (c *Config) WithHTTPClient(client *http.Client) *Config

Constants

const (
	// TypeUnspecified - Unspecified feature type.
	TypeUnspecified = iota
	// FaceDetection - Run face detection.
	FaceDetection
	// LandmarkDetection - Run landmark detection.
	LandmarkDetection
	// LogoDetection - Run logo detection.
	LogoDetection
	// LabelDetection - Run label detection.
	LabelDetection
	// TextDetection - Run OCR with big text
	TextDetection
	// DocumentTextDetection - Run OCR on document
	DocumentTextDetection
	// SafeSearchDetection - Run various computer vision models to
	SafeSearchDetection
	// ImageProperties - compute image safe-search properties.
	ImageProperties
)

const Version = "v1.1.0"

Version represents pigeon's semantic version.

Functions

func DetectionType

func DetectionType(d int) string

DetectionType returns a value of detection type.

func NewAnnotateImageContent

func NewAnnotateImageContent(body []byte) *vision.Image

NewAnnotateImageContent returns a pointer to a new vision's Image. It's contained image content, represented as a stream of bytes.

func NewAnnotateImageContentRequest

func NewAnnotateImageContentRequest(body []byte, features ...*vision.Feature) (*vision.AnnotateImageRequest, error)

NewAnnotateImageContentRequest returns a pointer to a new vision's AnnotateImagesRequest.

func NewAnnotateImageSource

func NewAnnotateImageSource(source string) *vision.Image

NewAnnotateImageSource returns a pointer to a new vision's Image. It's contained external image source (i.e. Google Cloud Storage image location).

func NewAnnotateImageSourceRequest

func NewAnnotateImageSourceRequest(source string, features ...*vision.Feature) (*vision.AnnotateImageRequest, error)

NewAnnotateImageSourceRequest returns a pointer to a new vision's AnnotateImagesRequest.

func NewFeature

func NewFeature(d int) *vision.Feature

NewFeature returns a pointer to a new vision's Feature object.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

A Client provides cloud vision service.

func New

func New(c *Config, httpClient ...*http.Client) (*Client, error)

New returns a pointer to a new Client object.

func (Client) ImagesService

func (c Client) ImagesService() *vision.ImagesService

ImagesService returns a pointer to a vision's ImagesService object.

func (Client) NewAnnotateImageRequest

func (c Client) NewAnnotateImageRequest(v interface{}, features ...*vision.Feature) (*vision.AnnotateImageRequest, error)

NewAnnotateImageRequest returns a pointer to a new vision's AnnotateImagesRequest.

func (Client) NewBatchAnnotateImageRequest

func (c Client) NewBatchAnnotateImageRequest(list []string, features ...*vision.Feature) (*vision.BatchAnnotateImagesRequest, error)

NewBatchAnnotateImageRequest returns a pointer to a new vision's BatchAnnotateImagesRequest.

type Config

type Config struct {
	// The credentials object to use when signing requests.
	// Defaults to application credentials file.
	Credentials *credentials.Credentials

	// The HTTP client to use when sending requests.
	// Defaults to `http.DefaultClient`.
	HTTPClient *http.Client
}

A Config provides service configuration for service clients. By default, all clients will use the {defaults.DefaultConfig} structure.

func NewConfig

func NewConfig() *Config

NewConfig returns a new pointer Config object.

func (*Config) WithCredentials

func (c *Config) WithCredentials(creds *credentials.Credentials) *Config

WithCredentials sets a config Credentials value returning a Config pointer for chaining.

func (*Config) WithHTTPClient

func (c *Config) WithHTTPClient(client *http.Client) *Config

WithHTTPClient sets a config HTTPClient value returning a Config pointer for chaining.