cloudsight

package module
v0.0.0-...-30d95be Latest Latest
Warning

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

 Go to latest Published: Jan 18, 2018 License: MIT Imports: 19 Imported by: 0

README

cloudsight-go

GoDoc Build Status

A simple CloudSight API Client for Go programming language.

Status

This package is currently in beta status. It means the API may still change in backwards incompatible way.

Installation

$ go get github.com/cloudsight/cloudsight-go

Configuration

You need your API key and secret (if using OAuth1 authentication). They are available on CloudSight site after you sign up and create a project.

Usage

Import the cloudsight package:

import (
    ...

    "github.com/cloudsight/cloudsight-go"
)

Create a client instance using simple key-based authentication:

client, err := cloudsight.NewClientSimple("your-api-key")

Or, using OAuth1 authentication:

client, err := cloudsight.NewClientOAuth("your-api-key", "your-api-secret")

Send the image request using a file:

f, err := os.Open("your-file.jpg")
if err != nil {
	panic(err)
}

defer f.Close()

params := cloudsight.Params{}
params.SetLocale("en")
job, err := client.ImageRequest(f, "your-file.jpg", params)

Or, you can send the image request using a URL:

params := cloudsight.Params{}
params.SetLocale("en")
job, err := client.RemoteImageRequest("http://www.example.com/image.jpg", params)

Then, update the job status to see if it's already processed:

err := client.UpdateJob(job)
if job != cloudsight.StatusNotCompleted {
	// Done!
}

It usually takes 6-12 seconds to receive a completed response. You may use WaitJob() method to wait until the image is processed:

err := client.WaitJob(job, 30 * time.Second)

Note that Params is just a map[string]string so you may choose to use more "dynamic" approach:

params := map[string]string{
	"image_request[locale]": "en",
}
job, err := client.RemoteImageRequest("http://www.example.com/image.jpg", cloudsight.Params(params))

Consult the complete documentation.

Documentation

Overview

A simple CloudSight API client library. For full API documentation go to https://cloudsight.readme.io/v1.0/docs.

Index

Examples

Constants

View Source 
const BaseURL = "https://api.cloudsightapi.com"

Base API URL.

View Source 
const DefaultLocale = "en-US"

Default locale that will be used when none is specified in Params.

Variables

View Source 
var (
	ErrMissingKey          = errors.New("key cannot be empty")
	ErrMissingSecret       = errors.New("secret cannot be empty")
	ErrTimeout             = errors.New("poll timed out")
	ErrInvalidRepostStatus = errors.New("the job needs to have the timeout status")
)

Functions

This section is empty.

Types

type Client 

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

func NewClientOAuth 

func NewClientOAuth(key, secret string) (*Client, error)

Create a new Client instance that will authenticate using OAuth1 protocol.

Error (ErrMissingKey or ErrMissingSecret) will be returned if either key or secret is empty.

func NewClientSimple 

func NewClientSimple(key string) (*Client, error)

Create a new Client instance that will authenticate using simple key-based method.

ErrMissingKey will be returned if key is empty.

func (*Client) ImageRequest 

func (c *Client) ImageRequest(image io.Reader, filename string, params Params) (*Job, error)

Send an image for classification. The image may be a os.File instance any other object implementing io.Reader interface. The params parameter is optional and may be nil.

On success this method will immediately return a Job instance. Its status will initially be "not completed" as it usually takes 6-12 seconds for the server to process an image. In order to retrieve the annotation data, you need to keep updating the job status using the UpdateJob() method until the status changes. You may also use the WaitJob() method which does this automatically.

Example 
c, _ := NewClientSimple("api-key")
f, _ := os.Open("some-file.jpg")
defer f.Close()

params := Params{}
// Set the position to 50.0°N 19.0°E
params.SetLatitude(50.0)
params.SetLongitude(19.0)

job, err := c.ImageRequest(f, "some-file.jpg", params)
if err != nil {
	panic(err)
}

fmt.Println("Token:", job.Token)

Output:

func (*Client) RemoteImageRequest 

func (c *Client) RemoteImageRequest(url string, params Params) (*Job, error)

Send an image for classification. The image will be retrieved from the URL specified. The params parameter is optional and may be nil.

On success this method will immediately return a Job instance. Its status will initially be "not completed" as it usually takes 6-12 seconds for the server to process an image. In order to retrieve the annotation data, you need to keep updating the job status using the UpdateJob() method until the status changes. You may also use the WaitJob() method which does this automatically.

Example 
c, _ := NewClientSimple("api-key")
params := Params{}
// Set the position to 50.0°N 19.0°E
params.SetLatitude(50.0)
params.SetLongitude(19.0)

job, err := c.RemoteImageRequest("http://www.example.com/some-image.jpg", params)
if err != nil {
	panic(err)
}

fmt.Println("Token:", job.Token)

Output:

func (*Client) RepostJob 

func (c *Client) RepostJob(job *Job) error

Repost the job if it has timed out (StatusTimeout).

ErrInvalidRepostStatus will be returned if current job status is different than StatusTimeout.

func (*Client) UpdateJob 

func (c *Client) UpdateJob(job *Job) error

Contact the server and update the job status. This method does nothing if the status has already changed from "not completed".

After a request has been submitted, it usually takes 6-12 seconds to receive a completed response. We recommend polling for a response every 1 second after a 4 second delay from the initial request, while the status is "not completed". WaitJob() method does this automatically.

Example 
c, _ := NewClientSimple("api-key")
job, _ := c.RemoteImageRequest("http://www.example.com/some-image.jpg", nil)

time.Sleep(3 * time.Second)

for job.Status == StatusNotCompleted {
	time.Sleep(1 * time.Second)
	c.UpdateJob(job)
}

fmt.Println("Status:", job.Status, job.Status.Description())

Output:

func (*Client) WaitJob 

func (c *Client) WaitJob(job *Job, timeout time.Duration) error

Wait for the job until it has been processed. This method will block for up to timeout seconds. After that ErrTimeout will be returned. If the timeout parameter is set to 0, WaitJob() will wait infinitely.

This method will wait for 4 seconds after the initial request and then will call UpdateJob() method every second until the status changes.

type Job 

type Job struct {
	// Image description as annotated by the API.
	Name string

	// Current job status.
	Status JobStatus

	// Time To Live.
	TTL float64

	// Token uniquely identifying the job.
	Token string

	// URL to the image as stored on CloudSight API servers.
	URL string

	// The reason for the job being skipped, if any.
	SkipReason SkipReason
	// contains filtered or unexported fields
}

Job is a result of sending an image to CloudSight API.

type JobStatus 

type JobStatus string

Possible values for current job status. 

const (
	// Recognition has not yet been completed for this image. Continue polling
	// until response has been marked completed.
	StatusNotCompleted JobStatus = "not completed"

	// Recognition has been completed. Annotation can be found in Name and
	// Categories field of Job structure.
	StatusCompleted JobStatus = "completed"

	// Token supplied on URL does not match an image.
	StatusNotFound JobStatus = "not found"

	// Image couldn't be recognized because of a specific reason. Check the
	// SkipReason field.
	StatusSkipped JobStatus = "skipped"

	// Recognition process exceeded the allowed TTL setting.
	StatusTimeout JobStatus = "timeout"
)

func (JobStatus) Description 

func (s JobStatus) Description() string

Return a detailed description of the job status.

type Params 

type Params map[string]string

Additional API parameters.

func (Params) SetAltitude 

func (p Params) SetAltitude(alt float64)

Set the altitude for additional geolocation context.

func (Params) SetDeviceID 

func (p Params) SetDeviceID(id string)

Set a unique ID generated for the device sending the request. We recommend generating a UUID.

func (Params) SetFocusAbsolute 

func (p Params) SetFocusAbsolute(x, y int) error

Set an absolute focal point on image for specificity.

The point uses North-West gravity (0, 0 corresponds to upper-left corner), for which to place a hightlight of attention on the image. In the event there are many identifiable objects in the image, this attempts to place importance on the ones closest to the focal point. This method accepts absolute coordinates (ie. a 400x400 image would have 0 through 400 for each axis).

func (Params) SetFocusRelative 

func (p Params) SetFocusRelative(x, y float64) error

Set a relative focal point on image for specificity.

The point uses North-West gravity (0.0, 0.0 corresponds to upper-left corner), for which to place a hightlight of attention on the image. In the event there are many identifiable objects in the image, this attempts to place importance on the ones closest to the focal point. This method accepts relative coordinates (0.0 through 1.0).

func (Params) SetLanguage 

func (p Params) SetLanguage(lang string)

Set the language of the request. The response will be returned in this language. The default is "en".

func (Params) SetLatitude 

func (p Params) SetLatitude(lat float64) error

Set the latitude for additional geolocation context.

func (Params) SetLocale 

func (p Params) SetLocale(locale string)

Set the locale of the request. Default is "en-US".

func (Params) SetLongitude 

func (p Params) SetLongitude(lon float64) error

Set the longitute for additional geolocation context.

func (Params) SetMaxTTL 

func (p Params) SetMaxTTL()

Set the maximum deadline before expired state is set.

func (Params) SetPosition 

func (p Params) SetPosition(lat, lon, alt float64) error

Set the position for additional geolocation context.

func (Params) SetTTL 

func (p Params) SetTTL(ttl int) error

Set the deadline in seconds before expired state is set. Use a high ttl for low-priority image requests. Use `SetMaxTTL()` for maximum deadline.

type SkipReason 

type SkipReason string

The API may choose not to return any response for given image. SkipReason type includes possible reasons for such behavior. 

const (
	// Offensive image content.
	ReasonOffensive SkipReason = "offensive"

	// Too blurry to identify.
	ReasonBlurry SkipReason = "blurry"

	// Too close to identify.
	ReasonClose SkipReason = "close"

	// Too dark to identify.
	ReasonDark SkipReason = "dark"

	// Too bright to identify.
	ReasonBright SkipReason = "bright"

	// Content could not be identified.
	ReasonUnsure SkipReason = "unsure"
)

func (SkipReason) Description 

func (r SkipReason) Description() string

Return a detailed description of the skip reason.

Source Files

View all Source files

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.