av/input/gvctrl/gvctrl.go

/*
DESCRIPTION
  gvctrl.go provides exported functionality of a basic API to allow programmatic
  control over the GeoVision camera (namely the GV-BX4700) through the HTTP
  server used for settings control. See package documentation for further
  information on the API.

AUTHORS
  Saxon A. Nelson-Milton <saxon@ausocean.org>

LICENSE
  Copyright (C) 2019 the Australian Ocean Lab (AusOcean)

  It is free software: you can redistribute it and/or modify them
  under the terms of the GNU General Public License as published by the
  Free Software Foundation, either version 3 of the License, or (at your
  Option) any later version.

  It is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  for more details.

  You should have received a copy of the GNU General Public License
  in gpl.txt.  If not, see http://www.gnu.org/licenses.
*/

// Package gvctrl provides a basic API for programmatic control of the
// web based interface provided by GeoVision cameras. This API has been
// developed and tested only with the GV-BX4700, and therefore may not work
// with other models without further evolution.
//
// Settings on a GeoVision camera are updated using the Set function. One or
// more option functions may be provided to control camera function.
package gvctrl

import (
	"fmt"
	"math/rand"
	"net/http"
	"net/http/cookiejar"
	"strconv"
	"time"
)

// Option describes a function that will apply an option to the passed s.
type Option func(s settings) (settings, error)

// Set will log in to the camera at host and submit a form of settings. The
// settings form is populated with values influenced by the optional options
// passed. Available options are defined below this function.
//
// The following defaults are applied to each configurable parameter if not
// influenced by the passed options:
// codec: H264
// resolution: 640x360
// framerate: 25
// variable bitrate: off
// variable bitrate quality: good
// vbr bitrate: 250 kbps
// cbr bitrate: 512 kbps
// refresh: 2 seconds
func Set(host string, options ...Option) error {
	// Randomly generate an ID our client will use.
	const (
		minID = 10000
		maxID = 99999
	)
	rand.Seed(time.Now().UTC().UnixNano())
	id := strconv.Itoa(maxID + rand.Intn(maxID-minID))

	// Create a client with a cookie jar.
	jar, err := cookiejar.New(nil)
	if err != nil {
		return fmt.Errorf("could not create cookie jar, failed with error: %v", err)
	}

	client := &http.Client{
		Timeout: time.Duration(5 * time.Second),
		Jar:     jar,
	}

	// Get the request body required for log in.
	body, err := genLogIn(client, id, host)
	if err != nil {
		return fmt.Errorf("could not generate log in request data: %v", err)
	}

	// Log in using generated log in request body.
	err = logIn(client, id, host, body)
	if err != nil {
		return fmt.Errorf("could not logIn: %v", err)
	}

	// Apply the options to the settings specified by the user.
	s := newSettings()
	for _, op := range options {
		s, err = op(s)
		if err != nil {
			return fmt.Errorf("could not action Option: %v", err)
		}
	}

	// Submit the settings to the server.
	err = submitSettings(client, id, host, s)
	if err != nil {
		return fmt.Errorf("could not submit settings: %v", err)
	}
	return nil
}

// Codec is a video codec.
type Codec string

// The avilable codecs that may be selected using CodecOut below.
const (
	CodecH265  Codec = "28"
	CodecH264  Codec = "10"
	CodecMJPEG Codec = "4"
)

// CodecOut will set the video codec outputted by the camera. The available
// codec options are listed above as consts.
func CodecOut(c Codec) Option {
	return func(s settings) (settings, error) {
		switch c {
		case CodecH265, CodecH264, CodecMJPEG:
			s.codec = c
			return s, nil
		default:
			return s, fmt.Errorf("unknown Codec: %v", c)
		}
	}
}

// Height will set the height component of the video resolution. Available
// heights are 256, 360 and 720.
func Height(h int) Option {
	return func(s settings) (settings, error) {
		v, ok := map[int]string{256: res256, 360: res360, 720: res720}[h]
		if !ok {
			return s, fmt.Errorf("invalid display height: %d", h)
		}
		s.res = v
		return s, nil
	}
}

// FrameRate will set the frame rate of the video. This value is defined in
// units of frames per second, and must be between 1 and 30 inclusive.
func FrameRate(f int) Option {
	return func(s settings) (settings, error) {
		if 1 > f || f > 30 {
			return s, fmt.Errorf("invalid frame rate: %d", f)
		}
		s.frameRate = strconv.Itoa(f * 1000)
		return s, nil
	}
}

// VariableBitrate with b set true will turn on variable bitrate video and
// with b set false will turn off variable bitrate (resulting in constant bitrate).
func VariableBitrate(b bool) Option {
	return func(s settings) (settings, error) {
		s.vbr = "0"
		if b {
			s.vbr = "1"
		}
		return s, nil
	}
}

// Quality defines an average quality of video from the camera.
type Quality string

// The available video qualities under variable bitrate. NB: it is not known
// what bitrates these correspond to.
const (
	QualityStandard  Quality = "4"
	QualityFair      Quality = "3"
	QualityGood      Quality = "2"
	QualityGreat     Quality = "1"
	QualityExcellent Quality = "0"
)

// VBRQuality will set the average quality of video under variable bitrate.
// The quality may be chosen from standard to excellent, as defined above.
func VBRQuality(q Quality) Option {
	return func(s settings) (settings, error) {
		switch q {
		case QualityStandard, QualityFair, QualityGood, QualityGreat, QualityExcellent:
			s.quality = q
			return s, nil
		default:
			return s, fmt.Errorf("invalid Quality: %v", q)
		}
	}
}

// VBRBitrate will set the maximal bitrate when the camera is set to variable
// bitrate. The possible values of maximal bitrate in kbps are predefined (by
// the camera) as: 250, 500, 750, 1000, 1250, 1500, 1750, 2000, 2250 and 2500.
// If the passed rate does not match one of these values, the closest value is
// selected.
func VBRBitrate(r int) Option {
	return func(s settings) (settings, error) {
		var vbrRates = []int{250, 500, 750, 1000, 1250, 1500, 1750, 2000, 2250, 2500}
		if s.vbr == "1" {
			s.vbrBitrate = convRate(r, vbrRates)
			return s, nil
		}
		return s, nil
	}
}

// CBRBitrate will select the bitrate when the camera is set to constant bitrate.
// The possible values of bitrate are predefined for each resolution as follows:
// 256p: 128, 256, 512, 1024
// 360p: 512, 1024, 2048, 3072
// 720p: 1024, 2048, 4096, 6144
// If the passed rate does not align with one of these values, the closest
// value is selected.
func CBRBitrate(r int) Option {
	return func(s settings) (settings, error) {
		var (
			cbrRates256 = []int{128, 256, 512, 1024}
			cbrRates360 = []int{512, 1024, 2048, 3072}
			cbrRates720 = []int{1024, 2048, 4096, 6144}
		)

		switch s.res {
		case res720:
			s.cbrBitrate = convRate(r, cbrRates720)
		case res360:
			s.cbrBitrate = convRate(r, cbrRates360)
		case res256:
			s.cbrBitrate = convRate(r, cbrRates256)
		default:
			panic("bad resolution")
		}
		return s, nil
	}
}

// Refresh will set the intra refresh period. The passed value is in seconds and
// must be between .25 and 5 inclusive. The value will be rounded to the nearest
// value divisible by .25 seconds.
func Refresh(r float64) Option {
	return func(s settings) (settings, error) {
		const (
			maxRefreshPeriod = 5
			minRefreshPeriod = .25
		)

		if minRefreshPeriod > r || r > maxRefreshPeriod {
			return s, fmt.Errorf("invalid refresh period: %g", r)
		}

		refOptions := []int{250, 500, 1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500, 5000}
		s.refresh = strconv.Itoa(refOptions[closestValIdx(int(r*1000), refOptions)])
		return s, nil
	}
}