grid

package module
v0.2.3 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2016 License: Apache-2.0 Imports: 13 Imported by: 0

README

GoDoc Apache V2 License Build Status

grid-sdk-go

grid-sdk-go provides two key elements:

  • a Go package for accessing the GRiD API, and
  • a Go CLI for interacting with GRiD.

Installing

Use go get to install the latest version of both the CLI and the library.

$ go get -v github.com/venicegeo/grid-sdk-go/...

To install.

$ go install github.com/venicegeo/grid-sdk-go/...

To include it in your application.

import "github.com/venicegeo/grid-sdk-go"

Using the GRiD CLI

The first time we run grid, we must provide our GRiD credentials. These can be updated at any time by running grid configure.

$ grid configure
GRiD Username: johnsmith
GRiD Password:
GRiD API Key: MyAPI-key
GRiD Base URL: https://rsgis.erdc.dren.mil/te_ba/

This will create (or update) the configuration file in $HOME/.grid/credentials on Linux/Mac OS X, or %HOMEPATH%/.grid/credentials on Windows. This credentials file will be used each time GRiD authentication is required.

To get an overview of the available commands, just type grid.

$ grid
grid is a command-line interface to the GRiD database.

Usage:
  grid [command]

Available Commands:
  add         Add an AOI
  configure   Configure the CLI
  export      Initiate a GRiD Export
  lookup      Get suggested AOI name
  ls          List AOI/Export/File details
  pull        Download File
  task        Get task details
  version     Print the version number of the GRiD CLI

Flags:
  -h, --help   help for grid

Use "grid [command] --help" for more information about a command.

To view a complete listing of user AOIs:

$ grid ls
PRIMARY KEY    NAME    CREATED AT
1              Foo     2015-06-22T08:15:33.513
2              Bar     2013-12-17T14:08:53.316

To view details of an individual AOI:

$ grid ls 1

NAME: Foo
CREATED AT: 2014-02-07T14:22:44.437

RASTER COLLECTS
PRIMARY KEY    NAME                   DATATYPE
101            20091113_Foo           EO

POINTCLOUD COLLECTS
PRIMARY KEY    NAME                   DATATYPE
201            20101106_Foo           LAS 1.2  

EXPORTS
PRIMARY KEY    NAME                   DATATYPE    STARTED AT
301            Foo_2013-Sep-11.zip    N/A         2013-09-11T14:32:23.292031
302            Foo_2013-Sep-11.zip    N/A         2013-09-11T11:43:38.729971

Or multiple AOIs:

$ grid ls 1 2

You can also mix a match AOI and export primary keys (collect IDs are not currently available):

$ grid ls 1 301

To download an exported file:

$ grid pull 7

To get a suggested AOI name:

$ grid lookup "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))"
Great Sand Sea

To add an AOI (the AOI is automatically named using the name provided by grid lookup):

$ grid add "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))"
Successfully created AOI "Great Sand Sea" with primary key "2880" at 2016-04-01T15:59:00.587

To export a point cloud:

$ grid export -h
Export is used to initiate a GRiD export for the AOI and for each of the provided collects.

Usage:
  grid export [AOI] [Collects]... [flags]

Currently, only point cloud exports are available via the CLI. Each export requires specification of exactly one AOI primary key, and one or more point cloud collect primary keys (these will be merged into a single file). The API returns a task ID (for task status queries), and an export ID to later retrieve export details (e.g., grid ls <export ID>).

$ grid export 1 201
TASK ID                               EXPORT ID
c7def4ee-8b47-4434-b4f5-2eecf984c0a6  303

To get export task status:

$ grid task c7def4ee-8b47-4434-b4f5-2eecf984c0a6
ID                                    NAME                          STATE
c7def4ee-8b47-4434-b4f5-2eecf984c0a6  export.tasks.generate_export  RUNNING

Using the library

Basic usage

Simply create a GRiD client, and then begin making requests.

package main

import "github.com/venicegeo/grid-sdk-go"

func main() {
  // Most users of the GRiD SDK simply need to create the client as shown. This
  // call will retrieve credentials, the API key, and base URL from the
  // configuration file and create the GRiD client accordingly.
  g := grid.New()
  if g == nil {
    panic("There must not be a credentials file!")
  }

  // Get details of the AOI with primary key of 100. The GRiD client does not
  // panic or set any HTTP status codes on error. Errors are returned from each
  // request, along with the HTTP response, for consumers of the SDK to act on
  // these as they see fit.
  aoiListObject, _, err := g.GetAOI(100)
  if err != nil {
    panic(err)
  }
}
Configuration

This example demonstrates the usage of GetConfig() to check for valid configuration settings prior to creating the client.

package main

import "github.com/venicegeo/grid-sdk-go"

func main() {
  // The SDK provides a function to parse an existing config file and return the
  // authorization string, API key, and base URL as a struct. While the config
  // is not used in this context, it may be useful to ensure that the config
  // file exists and is valid prior to creating the client.
  _, err := grid.GetConfig()
  if err != nil {
    panic(err)
  }

  // As before, we create a new client, and get details on the AOI with primary
  // key of 100.
  g := grid.New()
  if g == nil {
    panic("Are you sure the configuration file is valid?")
  }

  aoiListObject, _, err := g.GetAOI(100)
  if err != nil {
    panic(err)
  }
}
Advanced usage

For now, the GRiD client can also be constructed directly, bypassing the credentials file altogether.

package main

import (
  "crypto/tls"
  "encoding/base64"
  "net/http"
  "net/url"

  "github.com/venicegeo/grid-sdk-go"
)

func main() {
  // GRiD uses basic authentication. An authorization string is formed by base64
  // encoding the string formed by concatenating the user's username, a colon,
  // and the user's password.
  auth := base64.StdEncoding.EncodeToString([]byte("johnsmith:password"))

  // The GRiD client expects the base URL to be provided as type URL, so we
  // begin by parsing the provided URL string.
  baseURL, _ := url.Parse("https://rsgis.erdc.dren.mil/te_ba/")

  // For users wishing to construct the GRiD client directly (perhaps with a
  // different transport), this is entirely possible.
  g = &grid.Grid{
    Auth:    auth,
    Key:     "MyAPI-key",
    BaseURL: baseURL,
    Transport: &http.Transport{
      TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
    },
  }

  // We can still use this client to get the AOI with primary key of 100.
  aoiListObject, _, err := g.GetAOI(100)
  if err != nil {
    panic(err)
  }
}

Configuration

One method of obtaining GRiD credentials (the only one currently supported) is to read them from a configuration file, thus avoiding the temptation to hard-code these sensitive values. The following example demonstrates the creation of a configuration file.

package main

import (
  "encoding/base64"
  "encoding/json"
  "os"

  "github.com/venicegeo/grid-sdk-go"
)

func main() {
  // Begin by creating the configuration file. This function ensures that the
  // file is created in one of the expected locations (platform-specific).
  file, err := grid.CreateConfigFile()
  if err != nil {
    panic(err)
  }
  defer file.Close()

  // As in our earlier example, we create a base64 encoded string composed of
  // the user's username and password.
  auth := base64.StdEncoding.EncodeToString([]byte("johnsmith:password"))

  // We then create a GRiD configuration object consisting of the authorization
  // string, API key, and base URL. If the base URL is empty, the default Test &
  // Evaluation instance of GRiD will be targeted.
  config := grid.Config{Auth: auth, Key: "MyAPI-key", URL: ""}

  // This object is encoded as JSON in the configuration file.
  json.NewEncoder(file).Encode(config)
}

Documentation

Overview

Package grid provides a client for using the GRiD API.

Portions of the grid package borrow heavily from https://github.com/google/go-github, a Go library for accessing the GitHub API, which is released under a BSD-style license (https://github.com/google/go-github/blob/master/LICENSE), with additional inspiration drawn from https://github.com/Medium/medium-sdk-go, a similar library for accessing the Medium API, and released under Apache v2.0.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckResponse 

func CheckResponse(r *http.Response) error

CheckResponse checks the API response for errors, and returns them if present. A response is considered an error if it has a status code outside the 200 range. API error responses are expected to have either no response body, or a JSON response body that maps to ErrorResponse. Any other response body will be silently ignored.

func CreateConfigFile added in v0.2.1 

func CreateConfigFile() (*os.File, error)

CreateConfigFile creates the config file for writing, overwriting existing.

Types

type AOI 

type AOI struct {
	// Fields Fields `json:"fields,omitempty"`
	Fields struct {
		Name         string `json:"name,omitempty"`
		CreatedAt    string `json:"created_at,omitempty"`
		IsActive     bool   `json:"is_active,omitempty"`
		Source       string `json:"source,omitempty"`
		User         int    `json:"user,omitempty"`
		ClipGeometry string `json:"clip_geometry,omitempty"`
		Notes        string `json:"notes,omitempty"`
	} `json:"fields,omitempty"`
	Model string `json:"model,omitempty"`
	Pk    int    `json:"pk,omitempty"`
}

AOI represents the AOI object that is returned by the AOI detail endpoint.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#aoi-object2

type AOIItem 

type AOIItem struct {
	ExportSet          []Export            `json:"export_set,omitempty"`
	RasterCollects     []RasterCollect     `json:"raster_collects,omitempty"`
	PointcloudCollects []PointcloudCollect `json:"pointcloud_collects,omitempty"`
	AOIs               []AOI               `json:"aoi,omitempty"`
	Success            *bool               `json:"success,omitempty"`
	Error              string              `json:"error,omitempty"`
}

AOIItem represents the AOI object that is returned by the AOI list endpoint.

Note: If the query fails, we get a completely different JSON object, containing Success and Error fields. Although we never actually receive Success = true, we can test to see if the Success field exists, in which case it is false, and our query failed.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#aoi-detail-object

type AOIResponse 

type AOIResponse map[string]AOIItem

AOIResponse represents the collection of AOIItems returned by the AOI list endpoint.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#aoi-object

type AddAOIResponse 

type AddAOIResponse map[string]interface{}

AddAOIResponse represents the response returned by the AOI add endpoint.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#aoi-detail-object

type Config added in v0.2.1 

type Config struct {
	Auth string `json:"auth"`
	Key  string `json:"key"`
	URL  string `json:"url"`
}

Config represents the config JSON structure.

func GetConfig added in v0.2.1 

func GetConfig() (Config, error)

GetConfig extracts config file contents.

type Error 

type Error struct {
	Resource string `json:"resource"` // resource on which the error occurred
	Field    string `json:"field"`    // field on which the error occurred
	Code     string `json:"code"`     // validation error code
}

An Error reports more details on an individual error in an ErrorResponse. These are the possible validation error codes: 

missing:
    resource does not exist
missing_field:
    a required field on a resource has not been set
invalid:
    the formatting of a field is invalid
already_exists:
    another resource has the same valid as this field

GitHub API docs: http://developer.github.com/v3/#client-errors

type ErrorResponse 

type ErrorResponse struct {
	Response *http.Response // HTTP response that caused this error
	Message  string         `json:"message"` // error message
	Errors   []Error        `json:"errors"`  // more detail on individual errors
}

An ErrorResponse reports one or more errors caused by an API request. GitHub API docs: http://developer.github.com/v3/#client-errors

func (*ErrorResponse) Error 

func (r *ErrorResponse) Error() string

type Export 

type Export struct {
	Status    string `json:"status,omitempty"`
	Name      string `json:"name,omitempty"`
	Datatype  string `json:"datatype,omitempty"`
	HSRS      string `json:"hsrs,omitempty"`
	URL       string `json:"url,omitempty"`
	Pk        int    `json:"pk,omitempty"`
	StartedAt string `json:"started_at,omitempty"`
}

Export represents the export object that is returned as part of an AOIItem.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#export-object

type ExportDetail 

type ExportDetail struct {
	ExportFiles []ExportFile `json:"exportfiles,omitempty"`
	TDASets     []TDASet     `json:"tda_set,omitempty"`
	Success     *bool        `json:"success,omitempty"`
	Error       string       `json:"error,omitempty"`
}

ExportDetail represents the export detail object that is returned by the export endpoint.

Note: If the query fails, we get a completely different JSON object, containing Success and Error fields. Although we never actually receive Success = true, we can test to see if the Success field exists, in which case it is false, and our query failed.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#export-detail-object

type ExportFile 

type ExportFile struct {
	URL  string `json:"url,omitempty"`
	Pk   int    `json:"pk,omitempty"`
	Name string `json:"name,omitempty"`
}

ExportFile represents the export file object that is returned by the export endpoint.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#exportfiles-object

type GenerateExportObject added in v0.2.1 

type GenerateExportObject struct {
	Started  bool   `json:"started,omitempty"`
	TaskID   string `json:"task_id,omitempty"`
	ExportID int    `json:"export_id,omitempty"`
}

GenerateExportObject represents the output from a Generate Export operation

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#generate-export-object

type GeneratePointCloudExportOptions added in v0.2.1 

type GeneratePointCloudExportOptions struct {
	Intensity         bool
	DimClassification bool
	Hsrs              string //EPSG code
	FileExportOptions string //individual or collect
	Compressed        bool
	SendEmail         bool
	GenerateDem       bool
	CellSpacing       float32
	PclTerrain        string  // urban, mountainous, suburban, or foliated
	SriHResolution    float32 // Horizontal resolution
}

GeneratePointCloudExportOptions represents the options for a Generate Point Cloud Export Operation

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#generate-point-cloud-export

func NewGeneratePointCloudExportOptions added in v0.2.1 

func NewGeneratePointCloudExportOptions() *GeneratePointCloudExportOptions

NewGeneratePointCloudExportOptions is a factory method for a GeneratePointCloudExportOptions that provides all defaults

type Geoname 

type Geoname struct {
	Name     string `json:"name,omitempty"`
	Geometry string `json:"provided_geometry,omitempty"`
}

Geoname represents the geoname object that is returned by the geoname endpoint.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#geoname-object

type Grid added in v0.2.1 

type Grid struct {
	Auth string
	Key  string
	// Base URL for API requests.  Defaults to GRiD TE, but can be
	// set to a domain endpoint to use with other instances.  BaseURL should
	// always be specified with a trailing slash.
	BaseURL   *url.URL
	Transport http.RoundTripper
}

Grid defines the GRiD client.

func New added in v0.2.1 

func New() (*Grid, error)

New returns a new GRiD API client.

func (*Grid) AddAOI added in v0.2.1 

func (g *Grid) AddAOI(name, geom string, subscribe bool) (*AddAOIResponse, *Response, error)

AddAOI uploads the given geometry to create a new AOI.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#add-aoi

func (*Grid) Do added in v0.2.1 

func (g *Grid) Do(req *http.Request, v interface{}) (*Response, error)

Do sends an API request and returns the API response. The API response is JSON decoded and stored in the value pointed to by v, or returned as an error if an API error has occurred. If v implements the io.Writer interface, the raw response body will be written to v, without attempting to first decode it.

func (*Grid) DownloadByPk added in v0.2.1 

func (g *Grid) DownloadByPk(pk int) (*Response, error)

DownloadByPk downloads the file specified by the user-provided primary key.

func (*Grid) GeneratePointCloudExport added in v0.2.1 

func (g *Grid) GeneratePointCloudExport(pk int, collects []string, options *GeneratePointCloudExportOptions) (*GenerateExportObject, *Response, error)

GeneratePointCloudExport does just that for the given PK and set of collects

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#generate-point-cloud-export

func (*Grid) GetAOI added in v0.2.1 

func (g *Grid) GetAOI(pk int) (*AOIItem, *Response, error)

GetAOI returns AOI details for the AOI specified by the user-provided primary key.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#get-aoi-details

func (*Grid) GetExport added in v0.2.1 

func (g *Grid) GetExport(pk int) (*ExportDetail, *Response, error)

GetExport returns export details for the export specified by the user-provided primary key.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#get-export-details

func (*Grid) ListAOIs added in v0.2.1 

func (g *Grid) ListAOIs(geom string) (*AOIResponse, *Response, error)

ListAOIs retrieves all AOIs intersecting the optional geometry.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#get-a-users-aoi-list

func (*Grid) Lookup added in v0.2.1 

func (g *Grid) Lookup(geom string) (*Geoname, *Response, error)

Lookup the suggested name for the given geometry.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#lookup-geoname

func (*Grid) NewRequest added in v0.2.1 

func (g *Grid) NewRequest(method, urlStr string, body interface{}) (*http.Request, error)

NewRequest creates an API request. A relative URL can be provided in urlStr, in which case it is resolved relative to the BaseURL of the Client. Relative URLs should always be specified without a preceding slash. If specified, the value pointed to by body is JSON encoded and included as the request body.

func (*Grid) TaskDetails added in v0.2.1 

func (g *Grid) TaskDetails(pk string) (*TaskObject, *Response, error)

TaskDetails returns the details for a GRiD task

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#generate-point-cloud-export

type PointcloudCollect 

type PointcloudCollect struct {
	Datatype string `json:"datatype,omitempty"`
	Pk       int    `json:"pk,omitempty"`
	Name     string `json:"name,omitempty"`
}

PointcloudCollect represents the pointcloud collect object that is returned as part of an AOIItem.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#collect-object

type RasterCollect 

type RasterCollect struct {
	Datatype string `json:"datatype,omitempty"`
	Pk       int    `json:"pk,omitempty"`
	Name     string `json:"name,omitempty"`
}

RasterCollect represents the raster collect object that is returned as part of an AOIItem.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#collect-object

type Response 

type Response struct {
	*http.Response
}

Response is a GitHub API response. This wraps the standard http.Response returned from GitHub and provides convenient access to things like pagination links.

type TDASet 

type TDASet struct {
	Status    string `json:"status,omitempty"`
	TDAType   string `json:"tda_type,omitempty"`
	Name      string `json:"name,omitempty"`
	URL       string `json:"url,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
	Pk        int    `json:"pk,omitempty"`
	Notes     string `json:"notes,omitempty"`
}

TDASet represents the TDA set object that is returned by the export endpoint.

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#tda-set-object

type TaskObject added in v0.2.1 

type TaskObject struct {
	Traceback string `json:"task_traceback,omitempty"`
	State     string `json:"task_state,omitempty"`
	Timestamp string `json:"task_tstamp,omitempty"`
	Name      string `json:"task_name,omitempty"`
	TaskID    string `json:"task_id,omitempty"`
}

TaskObject represents the state of a GRiD task

GRiD API docs: https://github.com/CRREL/GRiD-API/blob/master/composed_api.rst#task-object

Source Files

View all Source files

Directories

Path Synopsis
cli
grid command
grid/cmd
examples
pzsvc-grid command

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.