README
¶
ncs
Neural Compute Stick V2.0 API Go binding
NCSDK API V2 IS PARTIALLY BROKEN on macOS AT THE MOMENT -- EVERYTHING WORKS FINE ON LINUX
The code in this repository has been tested on the following Linux OS:
Distributor ID: Ubuntu
Description: Ubuntu 16.04.5 LTS
Release: 16.04
Codename: xenial
Linux ubuntu-xenial 4.4.0-134-generic #160-Ubuntu SMP Wed Aug 15 14:58:00 UTC 2018 x86_64 x86_64 x86_64 GNU/Linux
The Movidius NCSDK API coverage provided in this repo should give you all the tools to use Movidius NCS to perform Neural Network inference.
Quick start
On MacOS, clone macos-V2
branch:
$ git clone -b macos-V2 https://github.com/milosgajdos/ncsdk.git
Build ncsdk API libraries:
$ cd api/src && sudo make basicinstall pythoninstall
Test NCSDK example:
$ cd ../../examples/apps/hello_ncs_cpp/ && make run
Example Go program
The example below shows how to create and destroy the basic resource types the NCSDK API 2.0 provides. For more complex examples please see examples
package main
import (
"log"
"github.com/milosgajdos/ncs"
)
func main() {
var err error
defer func() {
if err != nil {
log.Fatalf("Error: %s", err)
}
}()
log.Printf("Attempting to create NCS device handle")
dev, e := ncs.NewDevice(0)
if e != nil {
err = e
return
}
defer dev.Destroy()
log.Printf("NCS device handle successfully created")
log.Printf("Attempting to open NCS device")
err = dev.Open()
if err != nil {
return
}
defer dev.Close()
log.Printf("NCS device successfully opened")
log.Printf("Attempting to create NCS graph handle")
graph, e := ncs.NewGraph("NCSGraph")
if e != nil {
err = e
return
}
defer graph.Destroy()
log.Printf("NCS graph handle successfully created")
log.Printf("Attempting to create NCS FIFO handle")
fifo, e := ncs.NewFifo("TestFIFO", ncs.FifoHostRO)
defer fifo.Destroy()
if e != nil {
err = e
return
}
log.Printf("NCS FIFO handle successfully created")
}
If your Movidius NCS device is plugged in you should see the following output when running the program above:
2018/08/27 00:43:00 Attempting to create NCS device handle
2018/08/27 00:43:00 NCS device handle successfully created
2018/08/27 00:43:00 Attempting to open NCS device
2018/08/27 00:43:03 NCS device successfully opened
2018/08/27 00:43:03 Attempting to create NCS graph handle
2018/08/27 00:43:03 NCS graph handle successfully created
2018/08/27 00:43:03 Attempting to create NCS FIFO handle
2018/08/27 00:43:03 NCS FIFO handle successfully created
Documentation
¶
Overview ¶
For more information about how to install the SDK go here: https://movidius.github.io/ncsdk/install.html
Index ¶
- Constants
- type Device
- type DeviceHWVersion
- type DeviceOption
- type DeviceState
- type DeviceThermalThrottle
- type Fifo
- func (f *Fifo) Allocate(d *Device, td *TensorDesc, numElem uint) error
- func (f *Fifo) Destroy() error
- func (f *Fifo) GetOption(opt FifoOption) ([]byte, error)
- func (f *Fifo) GetOptionWithByteSize(opt FifoOption, size uint) ([]byte, error)
- func (f *Fifo) ReadElem() (*Tensor, error)
- func (f *Fifo) RemoveElem() error
- func (f *Fifo) WriteElem(data []byte, metaData interface{}) error
- type FifoDataType
- type FifoOption
- type FifoOpts
- type FifoQueue
- type FifoState
- type FifoType
- type Graph
- func (g *Graph) Allocate(d *Device, graphData []byte) error
- func (g *Graph) AllocateWithFifosDefault(d *Device, graphData []byte) (*FifoQueue, error)
- func (g *Graph) AllocateWithFifosOpts(d *Device, graphData []byte, inOpts *FifoOpts, outOpts *FifoOpts) (*FifoQueue, error)
- func (g *Graph) Destroy() error
- func (g *Graph) GetOption(opt GraphOption) ([]byte, error)
- func (g *Graph) GetOptionWithByteSize(opt GraphOption, size uint) ([]byte, error)
- func (g *Graph) QueueInference(f *FifoQueue) error
- func (g *Graph) QueueInferenceWithFifoElem(f *FifoQueue, data []byte, metaData interface{}) error
- type GraphOption
- type GraphState
- type Option
- type Status
- type Tensor
- type TensorDesc
Constants ¶
const ( // MaxNameSize is the maximum length of device or graph name size MaxNameSize = 28 // ThermalBufferSize is the size of the temperature buffer as returned when querying device ThermalBufferSize = 100 // DebugBufferSize is the size of the debug information buffer as returned by API DebugBufferSize = 120 // VersionMaxSize is the max length of various version options (HW, firmewre etc.) as returned by API VersionMaxSize = 4 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Device ¶
type Device struct {
// contains filtered or unexported fields
}
Device is Neural Compute Stick (NCS) device
func NewDevice ¶
NewDevice creates new NCS device handle and returns it.
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncDeviceCreate.html
func (*Device) Close ¶
Close closes the communication channel with NCS device. It returns error if it fails to close the communication channel.
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncDeviceClose.html
func (*Device) Destroy ¶
Destroy destroys NCS device handle and frees associated resources. This function must be called for every device that was initialized with NewDevice().
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncDeviceDestroy.html
func (*Device) GetOption ¶
func (d *Device) GetOption(opt DeviceOption) ([]byte, error)
GetOption queries the value of an option for the device and returns it encoded in a byte slice. It returns error if it fails to retrieve the option value.
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncDeviceGetOption.html
func (*Device) GetOptionWithByteSize ¶
func (d *Device) GetOptionWithByteSize(opt DeviceOption, size uint) ([]byte, error)
GetOptionsWithSize queries NCS device options and returns it encoded in a byte slice of size elements. This function is similar to GetOption(), however as opposed to GetOption() which first queries the NCS device for the size of the requested options, it attempts to request the options data by specifying its size in raw bytes explicitly, hence it returns the queried options data faster. It returns error if it fails to retrieve the options or if the requested size of the options is invalid.
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncDeviceGetOption.html
func (*Device) Open ¶
Open initializes NCS device and opens device communication channel. It returns error if it fails to open or initialize the communication channel with the device.
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncDeviceOpen.html
type DeviceHWVersion ¶
type DeviceHWVersion int
DeviceHWVersion defines neural compute device hardware version
const ( MA2450 DeviceHWVersion = iota MA2480 )
func (DeviceHWVersion) String ¶
func (hw DeviceHWVersion) String() string
String implements fmt.Stringer interface
type DeviceOption ¶
type DeviceOption int
DeviceOption defines NCS device options. The options starting with RW are both gettable and settable. The options starting with RO are only gettable.
const ( // RODeviceThermalStats queries device temperatures in degrees Celsius. // This option returns []float64 array of max temperatures for the last ThermalBufferSize seconds. RODeviceThermalStats DeviceOption = (2000 + iota) // RODeviceThermalThrottling queries temperature throttling level. RODeviceThermalThrottle // RODeviceState queries the state of the device. RODeviceState // RODeviceMemoryUsed queries current memory in use on the device in bytes. RODeviceMemoryUsed // RODeviceMemorySize queries total memory available on the device in bytes. RODeviceMemorySize // RODeviceMaxFifoCount queries maximum number of FIFOs that can be allocated for the device. RODeviceMaxFifoCount // RODeviceAllocatedFifoCount queries number of FIFOs currently allocated for the device. RODeviceAllocatedFifoCount // RODeviceMaxMaxGraphCount queries the maximum number of graphs that can be allocated for the device. RODeviceMaxGraphCount // RODeviceAllocatedGraphCount queries the number of graphs currently allocated for the device. RODeviceAllocatedGraphCount // RODeviceClassLimit queries the highest device option class supported. RODeviceClassLimit // RODeviceFirmwareVersion queries the version of the firmware currently running on the device. RODeviceFirmwareVersion // RODeviceDebugInfo queries more detailed info when the result of API call is StatusMyriadError. RODeviceDebugInfo // RODeviceMVTensorVersion queries the version of the mvtensor library that was linked with the API. RODeviceMVTensorVersion // RODeviceName queries the internal name of the device. RODeviceName // RODeviceMaxExecutors is reserved for future use. RODeviceMaxExecutors // RODeviceHWVersion queries the hardware version of the device. RODeviceHWVersion )
func (DeviceOption) Decode ¶
func (do DeviceOption) Decode(data []byte, count int) (interface{}, error)
Decode decodes options data encoded in raw bytes and returns it in its native type. The returned data can be asserted into its native type. If the data contains more than one element you need to specify the number of expected elements via count. It returns error if the data fails to be decoded into the option native type.
func (DeviceOption) String ¶
func (do DeviceOption) String() string
String implements fmt.Stringer interface for DeviceOption
func (DeviceOption) Value ¶
func (do DeviceOption) Value() int
Value returns option value as integer
type DeviceState ¶
type DeviceState int
DeviceState represents NCS device state
const ( // DeviceCreated means NCS device handle has been created. DeviceCreated DeviceState = iota // DeviceOpened means NCS device handle has been opened. DeviceOpened // DeviceClosed means NCS device handle has been closed. DeviceClosed )
func (DeviceState) String ¶
func (ds DeviceState) String() string
String implements fmt.Stringer interface
type DeviceThermalThrottle ¶
type DeviceThermalThrottle int
DeviceThermalThrottle defines thermal throttle level
const ( // NoThrottle means no limit reached NoThrottle DeviceThermalThrottle = iota // LowerGuard means means lower guard temperature threshold of chip sensor has been reached // Short throttling time is in action between inferences to protect the device LowerGuard // UpperGuards means upper guard temperature of chip sensor has been reached // Long throttling time is in action between inferences to protect the device UpperGuard )
func (DeviceThermalThrottle) String ¶
func (dt DeviceThermalThrottle) String() string
String implements fmt.Stringer interface
type Fifo ¶
type Fifo struct {
// contains filtered or unexported fields
}
Fifo is NCSDK FIFO queue
func NewFifo ¶
NewFifo creates new FIFO queue with given name and returns it It returns error if it fails to create new queue
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncFifoCreate.html
func (*Fifo) Allocate ¶
func (f *Fifo) Allocate(d *Device, td *TensorDesc, numElem uint) error
Allocate allocates memory for a FIFO for the specified device based on the number of elements the FIFO will hold and tensorDesc, which describes the expected shape of the FIFO’s elements It returns error when it fails to allocate FIFO
More information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncFifoAllocate.html
func (*Fifo) Destroy ¶
Destroy destroys NCS FIFO handle and frees associated resources. This function must be called for every FIFO handle that was initialized with NewFifo()
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncFifoDestroy.html
func (*Fifo) GetOption ¶
func (f *Fifo) GetOption(opt FifoOption) ([]byte, error)
GetOptions queries FIFO options and returns it encoded in a byte slice It returns error if it fails to retrieve the options
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncFifoGetOption.html
func (*Fifo) GetOptionWithByteSize ¶
func (f *Fifo) GetOptionWithByteSize(opt FifoOption, size uint) ([]byte, error)
GetOptionsWithSize queries NCS fifo options and returns it encoded in a byte slice of size elements. This function is similar to GetOption(), however as opposed to GetOption() which first queries the NCS device for the size of the requested options, it attempts to request the options data by specifying its size in raw bytes explicitly, hence it returns the queried options data faster. It returns error if it fails to retrieve the options or if the requested size of the options is invalid.
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncFifoGetOption.html
func (*Fifo) ReadElem ¶
ReadElem reads an element from a FIFO, usually the result of an inference as a tensor, along with the associated user-defined data If it fails to read the element it returns error
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncFifoReadElem.html
func (*Fifo) RemoveElem ¶
RemoveElem removes an element from a FIFO If it fails to remove the element it returns error THIS FUNCTION IS NOT IMPLEMENTED YET
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncFifoRemoveElem.html
func (*Fifo) WriteElem ¶
WriteElem writes an element to a FIFO, usually an input tensor for inference along with some metadata If it fails to write the element it returns error
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncFifoWriteElem.html
type FifoDataType ¶
type FifoDataType int
FifoDataType defines possible data types for FIFOs.
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncFifoDataType_t.html
const ( // FifoFP16 data is in half precision (16 bit) floating point format (FP16). FifoFP16 FifoDataType = iota // FifoFP32 data is in full precision (32 bit) floating point format (FP32). FifoFP32 )
func (FifoDataType) String ¶
func (fd FifoDataType) String() string
String implements fmt.Stringer interface
type FifoOption ¶
type FifoOption int
FifoOption is FIFO option which can be used to query and set various FIFO properties. The options starting with RW are both gettable and settable. The options starting with RO are only gettable. All settable options except for RWFifoHostTensorDesc must be set before FIFO is allocated.
const ( // RWFifoType configure the fifo type to either of FifoType options RWFifoType FifoOption = iota // RWFifoConsumerCount is number of consumers of elements before the element is removed RWFifoConsumerCount // RWFifoDataType configures fifo data type to either of FifoDataType options RWFifoDataType // RWFifoDontBlock configures to return StatusOutOfMemory instead of blocking RWFifoNoBlock // ROFifoCapacity allows to query number of maximum elements in the buffer ROFifoCapacity // ROFifoReadFillLevel allows to query number of tensors in the read buffer ROFifoReadFillLevel // ROFifoWriteFillLevel allows to query number of tensors in a write buffer ROFifoWriteFillLevel // ROFifoGraphTensorDescriptor allows to query the tensor descriptor of the FIFO ROFifoGraphTensorDesc // ROFifoState allows to query FifoState ROFifoState // ROFifoName allows to query FIFO name ROFifoName // ROFifoElemDataSize allows to query element data size in bytes ROFifoElemDataSize // RWFifoHostTensorDesc is tensor descriptor, defaults to none strided channel minor RWFifoHostTensorDesc )
func (FifoOption) Decode ¶
func (fo FifoOption) Decode(data []byte, count int) (interface{}, error)
Decode decodes options data encoded in raw bytes and returns it in its native type. The returned data can be asserted into its native type. If the data contains more than one element you need to specify the number of expected elements via count. It returns error if the data fails to be decoded into the option native type.
func (FifoOption) String ¶
func (fo FifoOption) String() string
String implements fmt.Stringer interface
type FifoOpts ¶
type FifoOpts struct { // Type is FIFO type Type FifoType // DataType is FIFO data type DataType FifoDataType // NumElem is a max number of elements that the FIFO will be able to contain NumElem int }
FifoOpts specifies FIFO configuration options
type FifoType ¶
type FifoType int
FifoType defines FIFO access types.
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncFifoType_t.html
type Graph ¶
type Graph struct {
// contains filtered or unexported fields
}
Graph is NCSDK neural network graph
func NewGraph ¶
NewGraph creates new Graph with given name and returns it It returns error if it fails to create new graph
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncGraphCreate.html
func (*Graph) Allocate ¶
Allocate allocates a graph on NCS device. This function sends graphData to NCS device. It does not allocate input or output FIFO queues. You have to either allocate them separately or use either AllocateWithFifosDefault() or AllocateWithFifosOpts() functions whcih conveniently create and allocate the FIFO queues. It returns error if it fails to allocate the graph on the device
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncGraphAllocate.html
func (*Graph) AllocateWithFifosDefault ¶
AllocateWithFifosDefault allocates a graph and creates and allocates FIFO queues with default parameters for inference. Both FIFOs have FifoDataType set to FifoFP32. Inbound FIFO queue is initialized with FifoHostWO type and outbound FIFO queue with FifoHostRO type. It returns FifoQueue or error if it fails to allocate the graph.
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncGraphAllocateWithFifos.html
func (*Graph) AllocateWithFifosOpts ¶
func (g *Graph) AllocateWithFifosOpts(d *Device, graphData []byte, inOpts *FifoOpts, outOpts *FifoOpts) (*FifoQueue, error)
AllocateWithFifosOpts allocates a graph and creates and allocates FIFO queues for inference. This function is similar to AllocateWithFifosDefault, but rather than initializing FIFOs with default values it accepts parameters that allow to specify FIFO queue parameters
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncGraphAllocateWithFifosEx.html
func (*Graph) Destroy ¶
Destroy destroys NCS graph handle and frees associated resources. This function must be called for every graph that was initialized with NewGraph().
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncGraphDestroy.html
func (*Graph) GetOption ¶
func (g *Graph) GetOption(opt GraphOption) ([]byte, error)
GetOption queries the value of an option for a graph and returns it encoded in a byte slice It returns error if it failed to retrieve the option value
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncGraphGetOption.html
func (*Graph) GetOptionWithByteSize ¶
func (g *Graph) GetOptionWithByteSize(opt GraphOption, size uint) ([]byte, error)
GetOptionsWithSize queries NCS grapg options and returns it encoded in a byte slice of size elements. This function is similar to GetOption(), however as opposed to GetOption() which first queries the NCS device for the size of the requested options, it attempts to request the options data by specifying its size in raw bytes explicitly, hence it returns the queried options data faster. It returns error if it fails to retrieve the options or if the requested size of the options is invalid.
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncGraphGetOption.html
func (*Graph) QueueInference ¶
QueueInference queues data for inference to be processed by a graph with specified input and output FIFOs If it fails to queue the data tensor it returns error
For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncGraphQueueInference.html
func (*Graph) QueueInferenceWithFifoElem ¶
QueueInferenceWithFifoElem writes an element to a FIFO, usually an input tensor for inference, and queues an inference to be processed by a graph. This is a convenient way to write an input tensor and queue an inference in one call If it fails to queue the data tensor it returns error For more information: https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/ncGraphQueueInferenceWithFifoElem.html
type GraphOption ¶
type GraphOption int
GraphOption defines graph options The options starting with RW are both gettable and settable The options starting with RO are only gettable
const ( // ROGraphState is current state of the graph ROGraphState GraphOption = (1000 + iota) // ROGraphInferenceTime times taken per graph layer for the last inference in milliseconds ROGraphInferenceTime // ROGraphInputCount is number of inputs expected by the graph ROGraphInputCount // ROGraphOutputCount is he number of outputs expected by the graph. ROGraphOutputCount // ROGraphInputTensorDesc is an array of TensorDesc's, which describe the graph inputs in order ROGraphInputTensorDesc // ROGraphOutputTensorDesc is array of TensorDesc's, which describe the graph outputs in order ROGraphOutputTensorDesc // ROGraphDebugInfo provides more details when the result of a function call was StatusMyriadError ROGraphDebugInfo // ROGraphName is the name of the graph ROGraphName // ROGraphOptionClassLimit returns the highest option class supported ROGraphOptionClassLimit // ROGraphVersion is graph version ROGraphVersion // RWGraphExecutorsCount is not implemented yet RWGraphExecutorsCount // ROGraphInferenceTimeSize size of array for ROGraphInferenceTime option ROGraphInferenceTimeSize )
func (GraphOption) Decode ¶
func (g GraphOption) Decode(data []byte, count int) (interface{}, error)
Decode decodes options data encoded in raw bytes and returns it in its native type. The returned data then can be asserted into its native type. If the data contains more than one element you need to specify the number of expected elements via count. It returns error if the data fails to be decoded into the option native type.
func (GraphOption) String ¶
func (g GraphOption) String() string
String implements fmt.Stringer interface for GraphOption
type GraphState ¶
type GraphState int
GraphState defines states of a network graph
const ( // GraphCreated means the graph has been created, but it may not be initialized GraphCreated GraphState = iota // GraphAllocated means the graph has been initialized, and the graph has been allocated for a device GraphAllocated // GraphWaitingForInput means the graph is waiting for input. GraphWaitingForInput // GraphRunning means the graph is currently running an inference GraphRunning )
func (GraphState) String ¶
func (gs GraphState) String() string
String implements fmt.Stringer interface for GraphState
type Option ¶
type Option interface { // Value returns Option value as its integer code Value() int // Decode decodes raw byte slice option data as returned from NCS Decode([]byte, int) (interface{}, error) }
Option is NCS option
type Status ¶
type Status int
Status is the NCSDK API status code as returned by most API calls. It usually reports the status of the Neural Compute Stick.
const ( // StatusOK means the API function call worked as expected StatusOK Status = -iota // StatusBusy means device is busy, retry later. StatusBusy // StatusError means an unexpected error was encountered during the API function call. StatusError // StatusOutOfMemory means the host is out of memory. StatusOutOfMemory // StatusDeviceNotFound means no device has been found at the given index or name. StatusDeviceNotFound // StatusInvalidParameters means at least one of the given parameters is wrong. StatusInvalidParameters // StatusTimeout means there was a timeout in the communication with the device. StatusTimeout // StatusCmdNotFound means the file to boot the device was not found. StatusCmdNotFound // StatusNotAllocated means the graph or fifo has not been allocated.. StatusNotAllocated StatusUnauthorized // StatusUnsupportedGraphFile means the graph file version is not supported. StatusUnsupportedGraphFile // StatusUnsupportedConfigFile is reserved for future use. StatusUnsupportedConfigFile // StatusUnsupportedFeature means the operation used a feature unsupported by this firmware version. StatusUnsupportedFeature // StatusMyriadError when an error has been reported by device, use MVNC_DEBUG_INFO. StatusMyriadError // StatusInvalidDataLength means an invalid data length has been passed when getting or setting an option. StatusInvalidDataLength // StatusInvalidHandle means an invalid handle has been passed to a function. StatusInvalidHandle )
type Tensor ¶
type Tensor struct { // Data contains raw tensor data Data []byte // MetaData contains tensor metadata MetaData interface{} }
Tensor is graph tensor as returned from NCS
type TensorDesc ¶
type TensorDesc struct { // BatchSize contains number of elements. BatchSize uint // Channels contains number of channels (when dealing with digital images). Channels uint // Width is data width (i.e. number of matrix columns). Width uint // Height is data height (i.e. number of matrix rows). Height uint // Size is the total data size in the tensor. Size uint // CStride is channel stride (Stride in the channels' dimension). CStride uint // WStride is width stride (Stride in the horizontal dimension). WStride uint // HStride is height stride (Stride in the vertical dimension). HStride uint // DataType is data type of the tensor. DataType FifoDataType }
TensorDesc describes NCS graph inputs and outputs