## Bidstack Viewability Debugger

![Overview](overview.png)

### Table of contents

1. [How to enable data sending from the SDK](#how-to-enable-data-sending-from-the-sdk)
2. [Controls (camera)](#controls-camera)
3. [Definitions](#definitions)
4. [Parts of the scene](#parts-of-the-scene)
5. [Control options window](#control-options-window)
   1. [Server options](#server-options)
   2. [Display options](#display-options)
   3. [Camera options](#camera-options)
6. [Info window](#info-window)
   1. [Primary info / options](#primary-info-options)
   2. [Cameras](#cameras)
   3. [Ad spots](#ad-spots)
7. [Quad info window](#quad-info-window)

### How to enable data sending from the SDK

Define the environment variable `BIDSTACK_VIEWABILITY_DEBUG=<host>:<port>`, and then run the executable in a way that the environment variable is applied before creating an instance of the ad client.

- `<host>` is the IP address of hostname of the computer where the viewability debugger is launched.
- `<port> ` is the port which the viewability debugger is listening to.

The debugger must be running and listening to the same port before a connection from the SDK is attempted.

### Controls (camera)

- **move mouse while holding right mouse button** - turn the camera
- **W** - move forward
- **S** - move backwards
- **A** - move left
- **D** - move right
- **Q** - move up
- **Z** - move down
- **Shift** - move 10x faster

### Definitions

- **Quad** - a polygon made of 4 points, typically assumed to be planar
- **Ad spot** - a representation of a single advertising spot in the game world, defined by either a single quad or an array of grouped quads
  - each quad group denotes a single instance of a creative

### Parts of the scene

![Scene](scene.png)

- Grid color: gray
- Camera color: green, appearance: wireframe
- Ad spots:
  - Appearance: filled + outlined
  - When unselected:
    - Front color: light gray
    - Back color: dark gray
    - Forward/normal vector color: gray
  - When selected:
    - Front color: light orange
    - Back color: brown
    - Forward/normal vector color: dark orange

### Control options window

This is a window where it is possible to configure the behavior and current state of the debugger.

!["Control options" window](control-options-window.png)

#### Server options

- **Port** - the server port that would be used for listening to incoming connections
- **Start the server** - starts listening to the specified port for incoming connections
- **Stop the server** - stops listening to the port and disconnects all current connections

#### Display options

- **Grid scale** - the size of a single grid cell (unitless)
- **Draw disabled cameras** - draw the cameras whose screen occupancy value is currently 0
- **Ad spots**
  - **Draw hidden** - draw the ad spots for which the "visible" attribute is set to false
  - **Draw hidden sides** - draw the sides of the ad spots (front and/or back) which are currently set to invisible

#### Camera options

- **Speed** - the base speed of the camera
- **Position** - the world-space location of the camera
- **Yaw** - the angle of horizontal direction of the camera
- **Pitch** - the angle of vertical direction of the camera (-89 - 89)
- **Direction** - displays the direction vector of the camera, computed from yaw, pitch and the up axis
- **Z-up** / **Y-up** allows to select which up vector to use for the camera, (0;0;1) or (0;1;0) respectively
- **FOV** - field of view in degrees (1 - 179)
- **Z-near** - the distance of the near clipping plane of the camera, this is a tradeoff option between being able to see nearby things (low values) and avoiding z-fighting (high values)
- **Z-far** - the distance of the far clipping plane of the camera, this can be used to show or hide the distant parts of the scene

### Info window

This is a window that shows everything about the incoming viewability data.

!["Info" window (top)](info-window-part1.png)

#### Primary info / options

- **Current connection** - allows to select the currently displayed connection by IP address
- **Camera** - allows to select using which camera the scene is rendered, there are 5 possible options:
  - **Debugger** - this is the user-controllable camera
  - **Camera 0-3** - these are the cameras set by the viewability API
- **Last update time** - this is the time of the last call to update frame viewability
- **Dump all data** - saves a file called `viewdbg_<timestamp>.vwdmp` to the current working directory, containing the full state of the viewability system
- **Errors** - contains a list of date/time, error code (one of _ErrorCodeValues_) and call name for all detected API errors

#### Cameras

This section displays information about the currently defined cameras (0-3).

- **Screen occupancy** - the camera screen occupancy value (camera / screen area ratio), needs to be non-zero for the camera to be considered active
- **VP matrix** - the camera view-projection matrix

#### Ad spots

This section displays information about the currently defined ad spots.

!["Info" window (ad spots)](info-window-part2.png)

- **Search** - allows to enter a partial name to filter the contents of the list below
- **Items** - a list of currently active ad spots, optionally filtered by search text above
  - Each entry is in the following format: `[<id>] <name> (<x>;<y>;<z>)`
- **Type** - ad spot geometry type (quad or quad array)
- **Ad spot info** - shows the ad spot ID and visibility (overall + sides)
- **Viewability** - shows the viewability info computed using the current camera
  - **V (_visibility_)** - how much of the ad spot is visible
  - **SO (_screen occupancy_)** - how much of the screen does the ad spot occupy
  - **A (_viewing angle_)** - the angle of camera position with respect to the ad spot
- **Quad world matrix** (visible if ad spot type is "quad") - the matrix that defines the ad spot by transforming a [-1;1] quad into world space
- **View data** (visible if ad spot type is "quad array") - opens a window listing all the quad array information
- **Name** - the name of the ad spot
- **Notification ID** - the notification ID of the ad spot
- **Custom data** - the custom data (key-value string pairs) of the ad spot

### Quad info window

This window displays everything about the currently observed quad array.

!["Quad info" window](quad-info-window.png)

To open it, press the "View data" button in the Info window inside a quad array ad spot info block:

![Location of the "View data" button](quad-info-view-data.png)

Parts of the data:

- individual quads are separated by an empty line
- `[Group <n>]` - marks the start of a group
- `fraction: <...>` - defines the fraction of visibility that the quad contributes to the group
- `center: <...>` - the center position of the quad
- `normal: <...>` - the normal/forward vector of the quad
- `--- vertices ---` - starts a list of 4 points that define the quad