tinycv/README.md

Camera tiny control library

# tinycv-node

tinycv node库

# 支持操作系统

- windows
- macOS
- macOS M1

# Install依赖

windows
- `visual studio 2017 or 2019` (建议使用`vs2019`)
- `CMake` (建议使用最新版本)

macOS
- 'xcode'
- 'gcc' 或者 'clang' （系统一般自带clang)
- ‘CMake'

# Install

```bash
npm install tinycv
```

# 功能概述

- 设备管理，可以获取到所有USB设备和对应的子设备，呈现一个树形结构
- 摄像头控制，支持缩放、全景、倾斜等
- 视频处理，支持调亮度、锐度等
- 摄像头捕获+渲染
- USB监视
- 固件升级 (暂时支持有限)


# tinycv addon-api 接口指南

# Classes

[DeviceManager](#DeviceManager)

[Device](#Device)

[UsbEndpoint](#UsbEndpoint)

[TinycvCamera](#TinycvCamera)

[VideoCapture](#VideoCapture)

[VideoCaptureAbility](#VideoCaptureAbility)

[VideoFrameARGB](#VideoFrameARGB)

[UsbMonitor](#UsbMonitor)

[Fireware](#Fireware)




# <span id="DeviceManager">DevcieManager</span>
DeviceManager是一个静态对象，里面的方法可以直接访问, 不需要构造对象

* [DeviceManager](#DeviceManager)
* __static__
    * [.enumerateUsbEndpoint()](#DeviceManager+EnumerationUsbEndpoint)


## <span id="#DeviceManager+EnumerationUsbEndpoint">enumerateUsbEndpoint</span>
枚举所有的usb设备, 他可能与你平常接触的USB枚举不同，他将会分成usbendpoint和subdevices，subdevices是指在这个usb
设备下有多少个子设备

注意： 这里的usbendpoint GDUI等于 (0xA5DCBF10, 0x6530, 0x11D2, 0x90, 0x1F, 0x00, 0xC0, 0x4F, 0xB9, 0x51, 0xED)

|Param|Type|
|-----|-----|
|callback| function(array<[UsbEndpoint](#UsbEndpoint)>)

**example**
```js
function onEnumerationUsbEndpointFinish(err, usbEndpoints) {
    if (err != null) {
        console.log(err);
    }

    console.log("usbEndpoint size : ", usbEndpoints.length);

    usbEndpoints.forEach(function(usbEndpoint) {
        console.log("uniqueId : ", usbEndpoints.GetUniqueId());
        console.log("subDevices : ");
        const devices = usbEndpoints.GetSubDevices();
        devices.forEach(function(device) {
            console.log("deviceName : ", device.deviceName);
            console.log("unqiueId: ", device.uniqueId);
            console.log("instanceId : ", device.instanceId);
            console.log("type : " , device.type);
        });
    });
}

Devicemanager.enumerateUsbEndpoint(onEnumerationUsbEndpointFinish);
```

# <span id="UsbEndpoint">UsbEndpoint</span>
usb端点类，其中包含了此usb下的一堆子设备, 和一个uniqueId， 这个唯一ID可以用来唯一标识这个UsbEndpoint，他其实就是devicePath


* [UsbEndpoint](#UsbEndpoint)
* _instance_
    * [.getSubDevices()](#UsbEndpoint+GetSubDevices)
    * [.getUniqueId()](#UsbEndpoint+GetDisplayName)
    * [.getPid()](#UsbEndpoint+GetPid)
    * [.getVid()](#UsbEndpoint+GetVid)
    * [.getHub()](#UsbEndpoint+GetHub)
    * [.getPort()](#UsbEndpoint+GetPort)

<span id="UsbEndpoint+GetSubDevices">getSubDevices</span>

**注意：子设备只会包含HID、Camera、Microphone、Loudspeaker、storage几种类型，其余类型会被自动过滤**

**Param**: 无

**Retrun**: array<[Device](#Device)>


# <span id="Device">Devcie</span>

设备基础信息类，其中保存类设备名称、设备路径、设备实例ID、设备所属类型，这个类不需要你手动去构造，会通过函数UsbEndpoint.getSubDevices() 返回

* [Device](#Device)
    * [new Device()](#new_Device_new)
    * _property_
        * [.deviceName](#Device+GetDeviceName)
        * [.unqiueId](#Device+GetDevicePath)
        * [.instanceId](#Device+GetInstanceId)
        * [.type](#Device+GetDeviceType)
        * [.chromiumUniqueId](#Device+ChromiumDevicePath)
    * _method_
        * [.convertToChromiumDeviceId](#Device+ConvertToChromiumDeviceId)
    * _type_
        * [DeviceType](#Device+DeviceType)

## <span id="new_Device_new">new Device()</span>
Device构造函数

| Param| Type|
| -------- | --------|
| deviceName| String|
| devicePath| String|
| instanceId| String|
| deviceType| [DeviceType](#Device+DeviceType)|

## <span id="Device+GetDeviceName">deviceName</span>
获取设备显示名称

**Return** : String

## <span id="Device+GetDevicePath">uniqueId</span>
获取设备路径

**Return** : String

## <span id="Device+GetInstanceId">instanceId</span>
获取设备实例ID

**Return**: String

## <span id="Device+GetDeviceType">deviceType</span>
获取设备类型

**Return**: [DeviceType](#Device+DeviceType)

## <span id="Device+GetDeviceType">type</span>
获取设备类

## <span id="Device+DeviceType">DeviceType</span>

- camera ( 0 )
- microphone (1)
- loudspeaker (2)
- hid (3)
- storage (4)

js定义
```js
const deviceType = {
  camera: 0,
  mircrophone: 1,
  loudspeaker: 2,
  hid: 3,
  storage: 4,
  none: 5
};
```

## <span id="Device+ChromiumDevicePath">chromiumUniqueId</span>
获取chromium的uniqueId，这个路径主要是给convertToChromiumDeviceId使用

## <span id="Device+ConvertToChromiumDeviceId">convertToChromiumDeviceId</span>
生成和chromium一样的device_id和group_id

| Param| Type|
| ------| -----------|
|chromiumUniqueId| String|
|salt| String|
|frameOrigin| String|

* 第一个参数chromiumUniqueId它可以通过device.chromiumUniqueId获取
* 第二个参数在electron程序中，可以通过读取%appdata%/YOU_APP_NAME/Preferences来获取，他是一个JSON文件，文件中有一个{"device_id_salt":"F60EF71327A385940BA58205AF50DCD7"}, 第二个参数就是要填写device_id_salt的值
* 第三个参数他是你的root域名

    * 当地址栏为空时，frameOrigin为 "chrome://new-tab-page"
    * 当导航栏地址为"file://xxx"时，frameOrigin为 "file://"
    * 其他情况是你当前请求页面的root域名

**example**
```js
const device = new Device("deviceName", "uniqueId", "instanceId", 2);
console.log(device.uniqueId);
device.devicePath = "uniqueId2";
device.convertToChromiumDeviceId(device.chromiumUniqueId, "F60EF71327A385940BA58205AF50DCD7", "https://www.qq.com")
```

## <span id="TinycvCamera">TinycvCamera</span>
caemra管理类，包含了几个方法，Open和Close，Open用来打开一个Camera，使用Close来关闭一个Camera，其中Open方法是异步, Get提供给你方便获取已经Open过到capture

* [TinycvCamera](#TinycvCamera)
    * __static__
        * [.open](#TinycvCamera+Open)
        * [.close](#TinycvCamera+Close)
        * [.get](#TinycvCamera+Get)

```js

function onOpen(err, capture) {
if (err == null) {
    console.log(err);
    return;
}

// Dosomething

// Close
}

const uniqueId = "xxx"; // uniqueId可以从DeviceManger里面获取到，或者从UsbMonitor
TinycvCamera.open(uniqueId, onOpen);
```

## <span id="TinycvCamera+Open">open</span>

| Param| Type|
| ------| -----------|
|uniqueId| String|
|callback| function(err, [capture](#VideoCapture))|

## <span id="TinycvCamera+Close">close</a>
调用Open函数之后，记得使用close关闭

| Param| Type|
| ------| -----------|
|uniqueId| String|

## <span id="TinycvCamera+Get">get</span>

如果你调用了open函数成功了之后，在open callback之外还需要使用到capture对象，请使用这个函数获取capture对象, 如果对应的capture不存在，将会返回null


| Param| Type|
| ---------| -----------|
| uniqueId| String|


## <span id="VideoCapture">VideoCapture</span>
摄像头实际操作类，对象会通过Open创建
* [VideoCapture](#VideoCapture)
    * __interface__
        * [.startCapture](#VideoCapture+StartCapture)
        * [.stopCapture](#VideoCapture+StopCapture)
        * [.setCaptureHandler](#VideoCapture+SetCaptureHandler)
        * [.zoom](#VideoCapture+Zoom)
        * [.pan](#VideoCapture+Pan)
        * [.tilt](#VideoCapture+Tilt)
        * [.getZoomValueRange](#VideoCapture+GetZoomValueRange)
        * [.getPanValueRange](#VideoCapture+GetZoomValueRange)
        * [.getTiltValueRange](#VideoCapture+GetTiltValueRange)
        * [.setBrightness](#VideoCapture+SetBrightness)
        * [.setContrast](#VideoCapture+SetContrast)
        * [.setSaturation](#VideoCapture+SetSaturation)
        * [.setSharpness](#VideoCapture+SetSharpness)
        * [.setHue](#VideoCapture+SetHue)
        * [.setPowerLineFrequency](#VideoCapture+SetPowerLineFrequency)
        * [.getBrightness](#VideoCapture+GetBrightness)
        * [.getSaturation](#VideoCapture+GetSaturation)
        * [.getContrast](#VideoCapture+GetContrast)
        * [.getSharpness](#VideoCapture+GetSharpness)
        * [.getGetHue](#VideoCapture+GetHue)
        * [.getPowerLineFrequency](#VideoCapture+GetPowerLineFrequency)
        * [.getCapabilitys](#VideoCapture+GetCapabilitys)

**注意注意：在没有拿到画面的时候，获取当前值和设置当前值都是无效的**


- startCapture 开始视频捕获，在调用这个函数之前必须先调用setCapturehandler函数
- stopCapture 停止视频捕获，一般情况下用不到，使用TinycvCamera.close代替
- setCaptureHandler 设置视频流处理函数，函数类型function(frame), frame类型是[VideoFrameARGB](#VideoFrameARGB)
- zoom 数码变焦，int32
- pan 全景
- Tilt 倾斜
- getZoomValueRange、getPanValueRange、getTiltValueRange获取对应value范围
- setBrightness 设置亮度
- setContrast 设置对比度
- setSaturation 设置饱和度
- setSharpness 设置锐度
- setHue 设置色彩
- setPowerLineFrequency 设置电力线频率，也就是防闪烁
- getBrightness 获取亮度
- getContrast 获取对比度
- getSaturation 获取饱和度
- getSharpness 获取锐度
- getHue 获取色彩
- getPowerLineFrequency 获取电力线频率，也就是防闪烁
- getCapabilitys 获取所有capabilitys，返回类型 array [VideoCaptureAbility](#VideoCaptureAbility)


Get* 返回值
```js
{
    minValue: 0,
    maxValue: 100,
    value: 50,
    step: 1, // 如果step是1，你就不能设置50.5, 只能以step为增值或者减值
    defValue: 50,  // 默认值
    flag: 1 // 1自动，2手动
}
```

**example**

```js
const uniqueId = "xxx"; // uniqueId可以从DeviceManger里面获取到，或者从UsbMonitor

function onFrame(frame) {
    console.log(frame.size);
    console.log(frame.width);
    console.log(frame.height);
}

function onStartCaptured(err) {
    console.log(TinycvCamera.get().getSharpness());
}

function onOpen(err, capture) {
    if (err == null) {
        console.log(err);
        return;
    }

    console.log(capture.getBrightness());
    cpature.setBrightness(50);

    capture.setCaptureHandler(onFrame);
    capture.startCapture(onStartCaputred);
}

TinycvCamera.open(uniqueId, onOpen);
```

# <span id="VideoCaptureAbility">VideoCaptureAbility</span>
* [VideoCaptureAbility](#VideoCaptureAbility)
    * __property__
        * [.width](#VideoCaptureAbility+Width)
        * [.height](#VideoCaptureAbility+Height)
        * [.maxFps](#VideoCaptureAbility+MaxFps)


# <span id="VideoFrameARGB">VideoFrameARGB</span>

**只读**

* [VideoFrameARGB](#VideoFrameARGB)
    * __property__
        * [.width](#VideoFrameARGB+Width)
        * [.height](#VideoFrameARGB+Height)
        * [.bitCount](#VideoFrameARGB+BitCount)
        * [.data](#VideoFrameARGB+Data)


# <span id="UsbMonitor">UsbMonitor</span>
* [UsbMonitor](#UsbMonitor)
    * __static__
        * [.start](#UsbMonitor+Start)
        * [.stop](#UsbMonitor+Stop)
        * [.setDeviceInsertedHandler](#UsbMonitor+SetDeviceInsertedHandler)
        * [.setDeviceRemovedHandler](#UsbMonitor+SetDeviceRemovedHandler)

所有方法都是静态,可以直接调用, SetDeviceInsertedHandler,SetDeviceRemovedHandler必须在调用Start方法之前

**example**

```js
function onDeviceAdded(usbEndpoint) {
    const uniqueId = usbEndpoint.getUniqueId();
    const subdevices = usbEndpoint.getSubDevices();
}

function onDeviceRemoved(usbEndpoint) {
// Usb移除只有唯一id
    const uniqueId = usbEndpoint.getUniqueId();
}

UsbMonitor.setDeviceInsertedHandler(onDeviceAdded);
UsbMonitor.setDeviceRemovedHandler(onDeviceRemoved);
UsbMonitor.start();
```

# <span id="Fireware">Fireware</span>
* [Fireware](#Fireware)
    * [new Fireware()](#new_Fireware_new)
    * __property__
        * [.name](#Fireware+name)
        * [.version](#Fireware+version)
        * [.sn](#Fireware+sn)
        * [.pn](#Fireware+pn)
        * [.otakey](#Fireware+otakey)
        * [.onupgradefinished](#Fireware+onupgradefinished)
        * [.onupgradeprogressupdated](#Fireware+onupgradeprogressupdated)
    * __interface__
        * [.upgrade](#Fireware+Upgrade)

一个Fireware代表一个固件，其中分为两大模块，固件基础信息，和固件升级，固件基础信息包含固件名称、固件版本、固件SN、固件PN、固件OTAKEY等

## <span id="new_Fireware_new">new Fireware</span>
| Param| Type| Desc|
| -------- | --------| ----------- |
| UsbEndpoint| [UsbEndpoint](#UsbEndpoint)| 升级固件的Usb设备端点|

在创建Fireware对象时需要一个UsbEndpoint对象，这个对象可以通过DeviceManager.enumerateUsbEndpoint函数结合你当前open的Camera的Device来判断出该选择哪一个UsbEndpoint

**注意 new Fireware在失败情况下会抛异常，请注意处理**

## <span id="Fireware+onupgradefinished">onupgradefinished</span>
onupgradefinished类型是一个function, 在调用upgrade函数之后，所有的结果通知都通过这个函数告知使用者, 请在调用Upgrade之前设置这个属性

函数原型:
```js
onupgradefinished = function(firewareFilePath, code, msg) {
};
```

code 取值范围:

```js
// 除了0以外的都是失败
const upgradeState = {
  succeed: 0,
  updateAlreadyExists: 1,
  invaildFirewareFile: 2,
  alreadyNewestVersion: 3,
  firewareFileOversize: 4,
  switchUpgradeModeFailed: 5,
  findScsiDeviceFailed: 6,
  readFirewareFileContentFailed: 7,
  scsiLoadFailed: 8,
  writeUpgradeDataFailed: 9,
  checkUpgradeResultFailed: 10,
  versionCheckFailed: 11
  notSupport: 12
};
```

## <span id="Fireware+onupgradeprogressupdated">onupgradeprogressupdated</span>
onupgradeprogressupdated类型时一个function，在调用Upgrade函数之后，后续的更新进度会通过这个函数告知使用者，请在调用Upgrade之前设置这个属性

函数原型:
```js
// value是进度值，取值范围 1 - 100
onupgradeprogressupdated = function(value) {
};
```

## <span id="#Fireware+Upgrade">upgrade</span>
固件升级接口，Upgrade是一个异步接口，所有反馈都通过onupgradefinished和onupgradeprogressupdated通知, 当收到onupgradefinished的通知时，代表更新已经完成，code表达了更新的结果，当code时succeed时，更新成功.

**警告：一个Fireware代表一个固件，不要试图同时多次对一个Fireware调用upgrade，这样你将会收到updateAlreadyExists错误**

| Param| Type| Desc |
| ---------| -----------| --------------|
| firewarePath| String| 固件升级文件路径, 必须是UTF-8格式 |
| force| Boolean| 是否采用强制升级，如填true，将不会进行版本检查|


## example

```js
// usbEndpoint 可以使用 DeviceManager.EnumerationUsbEndpoint函数获取
const fireware = new Fireware(usbEndpoint);

// 基础信息获取
console.log(fireware.name)
console.log(fireware.version)
console.log(fireware.sn)
console.log(fireware.pn)
console.log(fireware.otakey)

//  升级之前的初始化
fireware.onupgradeprogressupdated = function(value) {
    console.log(value);
};

fireware.onupgradefinished = function(firewareFilePath, code, msg) {
    console.log("code : " + code);
    if (code != updateState.succeed) {
        // 升级失败
        console.log("msg: " + msg);
    } else {
        // 升级成功
    }
};


fireware.upgrade(firewareFilePath, false);
```