# Watcher

Watcher objects are plain object descriptors providing Lampix with the required information to start watching areas based on the behaviors described.

## Properties

* `name` (*string*): Literal string describing the Python class to instantiate and define the watcher's behavior (e.g `'NeuralNetworkClassifier'`, `'MovementBasedSegmenter'` etc.).
* `shape` (*Object*): Plain object with two properties, `type` and `shape` that defines the surface area for the watcher.
  * `type` (*string*): Defines shape type, and controls what the expected structure of `shape.data` will be. Accepted values:
    * `'rectangle'`
    * `'polygon'`
  * `data` (*Object*): Actual descriptor object for the contour of the watcher.
    * If `shape.type` is `'rectangle'`, the expected data structure is:
      * `posX` (*number*): top left X coordinate of rectangle
      * `posY` (*number*): top left Y coordinate of rectangle
      * `width` (*number*)
      * `height` (*number*)
    * If `shape.type` is `'polygon'`, a list of points is expected, with each point having the following data structure:
      * `x` (*number*): X coordinate of point
      * `y` (*number*): Y coordinate of point
* `onClassification` (*Function*): Callback used by Lampix to send information about recognized objects as a list with with recognized objects of the following structure:
  * `classTag` (*string*): Recognized class of the described object.
  * `objectId?` (*number, Optional*): ID representing the object. Useful when determining whether Lampix considers an object as new.
  * `outline?` (*Array, Optional*): Object with a property of `points` that describes the contour of the object as a polygon:
  * `metadata?` (*string*, Optional): Watcher specific information
* `onLocation` (*Function*): Callback used only by watchers that locate first, then classify. Called with a list of located objects that with a similar structure to the one above, except `classTag` is not mentioned since it has not been determined at the time of this call.
* `params?` (*Object*): Plain object with arbitrary props that can differ from watcher to watcher. See [standard watchers](https://api.lampix.co/application-development/standard-watchers)

## Notes

The only required property is `classTag`. Certain watchers that do not support more than one object at a time (e.g `NeuralNetworkClassifier`), will always provide a list with one recognized object that only has the `classTag` property. This is by design, to ensure consistency in the data format returned by the standard watchers.

## Example

```javascript
{
  name: 'DepthClassifier',
  shape: {
    type: "rectangle",
    data: {
      posX: 0,
      posY: 0,
      width: window.innerWidth,
      height: window.innerHeight
    }
  },
  params: {
    frames_until_stable: 5
  },
  onClassification: (objects) => draw(objects);
}
```

## Tips

In the example above, you can use `shape: lampix.helpers.rectangle(0, 0, window.innerWidth, window.innerHeight)` to achieve the same result.