# Align

The Align node provides a generic way to align
[`ImgFrame`](https://docs.luxonis.com/software-v3/depthai/depthai-components/messages/img_frame.md) and
[`Transformable`](https://docs.luxonis.com/software-v3/depthai/api/cpp.md) messages with each other. Either type can be the source
or the alignment target, including aligning an `ImgFrame` to any transformable message type.

Align runs on [RVC4](https://docs.luxonis.com/hardware/platform/rvc/rvc4.md) devices by default and can also run on the host.
Custom message alignment requires host execution and an override of `transformTo()`.

## How to place it

#### Python

```python
with dai.Pipeline() as pipeline:
    align = pipeline.create(dai.node.Align)
```

#### C++

```cpp
dai::Pipeline pipeline;
auto align = pipeline.create<dai::node::Align>();
```

## Inputs and Outputs

 * `input`: The message to transform.
 * `inputAlignTo`: The message whose `ImgTransformation` defines the target coordinate system.
 * `inputConfig`: Accepts `AlignConfig` messages to update alignment settings at runtime. Use `initialConfig` to configure the
   node before starting the pipeline.
 * `outputAligned`: The aligned message, with the same type as the message on `input`.
 * `passthroughInput`: The original input message used for the alignment.

## How it works

Align uses the `ImgTransformation` metadata carried by the source and target messages to map the source into the target coordinate
system. The source and target do not need to have the same message type. For example, you can align detections to an image, an
image to detections, or two transformable messages to each other.

For [`ImgDetections`](https://docs.luxonis.com/software-v3/depthai/depthai-components/messages/img_detections.md), this lets you
map detections from a neural network's input image onto a resized, cropped, rotated, or undistorted image for display.

## Usage

To align detections to an image, connect the output of an existing
[DetectionNetwork](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/detection_network.md) to `input` and the
target image stream to `inputAlignTo`. In this snippet, `manip` is an existing
[ImageManip](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/image_manip.md) node that produces the target
image.

#### Python

```python
align = pipeline.create(dai.node.Align)
detectionNetwork.out.link(align.input)
manip.out.link(align.inputAlignTo)

alignedDetectionsQueue = align.outputAligned.createOutputQueue()
```

#### C++

```cpp
auto align = pipeline.create<dai::node::Align>();
detectionNetwork->out.link(align->input);
manip->out.link(align->inputAlignTo);

auto alignedDetectionsQueue = align->outputAligned.createOutputQueue();
```

The output queue contains `ImgDetections` messages in the target image's coordinate system. To align the image to the detections
instead, swap the streams connected to `input` and `inputAlignTo`; the aligned output will then contain `ImgFrame` messages.

## Custom messages

Custom messages can derive from `TransformableBuffer` and override `transformTo(target)` to return a transformed copy. Attach the
source `ImgTransformation` to each message, transform its custom fields inside `transformTo()`, and set the target transformation
on the returned message.

Set Align to run on the host before starting the pipeline:

#### Python

```python
align.setRunOnHost(True)
```

#### C++

```cpp
align->setRunOnHost(true);
```

The custom message examples below define a line with two endpoints and override `transformTo()` to remap those endpoints into the
target image's coordinate system.

## Examples of functionality

| Example | Python | C++ |
| --- | --- | --- |
| Align `ImgDetections` to a transformed image | [Python
example](https://github.com/luxonis/depthai-core/blob/main/examples/python/Align/img_detections_align.py) | [C++
example](https://github.com/luxonis/depthai-core/blob/main/examples/cpp/Align/img_detections_align.cpp) |
| Align a custom message on the host | [Python
example](https://github.com/luxonis/depthai-core/blob/main/examples/python/Align/custom_message_align.py) | [C++
example](https://github.com/luxonis/depthai-core/blob/main/examples/cpp/Align/custom_message_align.cpp) |

## Reference

### dai::node::Align

Kind: class

Align node. Aligns ImgFrame and Transformable messages using ImgTransformation metadata.

#### std::shared_ptr< AlignConfig > initialConfig

Kind: variable

Initial config to use when aligning messages.

#### Input inputConfig

Kind: variable

Input message with ability to modify parameters in runtime. Default queue is non-blocking with size 4.

#### Input input

Kind: variable

Input message to be aligned. Can be either ImgFrame or any message that implements Transformable interface. Default queue is
non-blocking with size 4.

#### Input inputAlignTo

Kind: variable

Input align to message. Default queue is non-blocking with size 1.

#### Output outputAligned

Kind: variable

Outputs the input message aligned to the inputAlignTo message. Output message will be of the same type as input message.

#### Output passthroughInput

Kind: variable

Passthrough message on which the calculation was performed. Suitable for when input queue is set to non-blocking behavior.

#### Align & setNumFramesPool(int numFramesPool)

Kind: function

Specify number of frames in the pool

#### void setRunOnHost(bool runOnHost)

Kind: function

Specify whether to run on host or device By default, the node will run on device.

#### bool runOnHost()

Kind: function

Check if the node is set to run on host

#### void run()

Kind: function

#### void buildStage1()

Kind: function

Build stages;.

#### DeviceNodeCRTP()

Kind: function

#### DeviceNodeCRTP(const std::shared_ptr< Device > & device)

Kind: function

#### DeviceNodeCRTP(std::unique_ptr< Properties > props)

Kind: function

#### DeviceNodeCRTP(std::unique_ptr< Properties > props, bool confMode)

Kind: function

#### DeviceNodeCRTP(const std::shared_ptr< Device > & device, std::unique_ptr< Properties > props, bool confMode)

Kind: function

### Need assistance?

Head over to [Discussion Forum](https://discuss.luxonis.com/) for technical support or any other questions you might have.