# 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](/application-development/standard-watchers.md)

## 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.lampix.co/application-development/lampixjs/api/watcher.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.