Skip to content

Commit 27f2160

Browse files
jforbergJohan FörbergStiv-workjohan-hultberg-workisak-jacobsson
committed
Add an example program for Axoverlay 2.0
Co-authored-by: Johan Förberg <johanfb@axis.com> Co-authored-by: Stiv Abdullwahed <stiva@axis.com> Co-authored-by: Johan Hultberg <johanol@axis.com> Co-authored-by: Isak Jakobsson <isakj@axis.com> Co-authored-by: Daniel Myhrman <74043942+danielmyh@users.noreply.github.com>
1 parent 90113ae commit 27f2160

10 files changed

Lines changed: 795 additions & 1 deletion

File tree

‎.github/workflows/axoverlay2.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Build axoverlay2 application
2+
on:
3+
workflow_dispatch:
4+
push:
5+
paths:
6+
- 'axoverlay2/**'
7+
- '!axoverlay2/README.md'
8+
- '.github/workflows/axoverlay2.yml'
9+
jobs:
10+
test-app:
11+
name: Test app
12+
runs-on: ubuntu-latest
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
axis-os: ["12.10.68"]
17+
arch: ["armv7hf", "aarch64"]
18+
env:
19+
EXREPO: acap-native-examples
20+
EXNAME: axoverlay2
21+
steps:
22+
- uses: actions/checkout@v6
23+
- uses: docker/setup-buildx-action@v3
24+
25+
- name: Build ${{ env.EXNAME }} application
26+
env:
27+
imagetag: ${{ env.EXREPO }}_${{ env.EXNAME }}:${{ matrix.arch }}
28+
run: |
29+
docker image rm -f $imagetag
30+
cd $EXNAME
31+
docker build --no-cache --tag $imagetag --build-arg ARCH=${{ matrix.arch }} .
32+
docker cp $(docker create $imagetag):/opt/app ./build
33+
cd ..
34+
docker image rm -f $imagetag

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,12 @@ The examples are organized into logical groups to help you find the most relevan
7272

7373
### Graphical components
7474

75+
- [axoverlay2](./axoverlay2/)
76+
- An example in C that illustrates how to draw icons as overlays in a stream using the modern
77+
[Overlay API](https://developer.axis.com/acap/api#overlay2-API).
7578
- [axoverlay](./axoverlay/)
76-
- An example in C that illustrates how to draw plain boxes and text as overlays in a stream.
79+
- An example in C that illustrates how to draw plain boxes and text as overlays in a stream using
80+
the [Axoverlay API (Legacy)](https://developer.axis.com/acap/api#axoverlay-api-legacy).
7781
- [bounding-box](./bounding-box/)
7882
- An example in C that demonstrates how to portably draw burnt-in bounding boxes on selected video sources or channels.
7983
- [vdo-opencl-filtering](./vdo-opencl-filtering/)

‎axoverlay2/Dockerfile‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
ARG ARCH=armv7hf
2+
ARG VERSION=12.10.0-rc.5
3+
ARG UBUNTU_VERSION=24.04
4+
ARG REPO=docker-prod.se.axis.com/axisecp
5+
ARG SDK=acap-native-sdk
6+
7+
FROM ${REPO}/${SDK}:${VERSION}-${ARCH}-ubuntu${UBUNTU_VERSION}
8+
9+
# Building the ACAP application
10+
COPY ./app /opt/app/
11+
WORKDIR /opt/app
12+
RUN . /opt/axis/acapsdk/environment-setup* && acap-build .

‎axoverlay2/README.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
*Copyright (C) 2026, Axis Communications AB, Lund, Sweden. All Rights Reserved.*
2+
3+
# ACAP application drawing video overlays
4+
5+
This README file explains how to build an ACAP application that uses the axoverlay API, version 2.0.
6+
7+
Together with this README file, you should be able to find a directory called app. That directory contains the "axoverlay2" application source code which can easily be compiled and run with the help of the tools and step by step below.
8+
9+
For more information on Axoverlay2 API, please see the [Axis developer documentation](https://developer.axis.com/acap/4/api/#axoverlay2-api).
10+
11+
This example illustrates how to draw overlays in a video stream and Cairo is used as rendering API, see [documentation](https://www.cairographics.org/). In this example, a rotating and color-shifting icon is drawn.
12+
13+
## Getting started
14+
15+
These instructions will guide you on how to execute the code. Below is the structure and scripts used in the example:
16+
17+
```sh
18+
axoverlay2
19+
├── app
20+
│ ├── axoverlay2.c
21+
│ ├── LICENSE
22+
│ ├── Makefile
23+
│ └── manifest.json
24+
├── Dockerfile
25+
└── README.md
26+
```
27+
28+
- **app/axoverlay2.c** - Application to draw overlays using axoverlay 2.0 in C.
29+
- **app/LICENSE** - Text file that lists all open source licensed source code distributed with the application.
30+
- **app/Makefile** - Build and link instructions for the application.
31+
- **app/manifest.json** - Defines the application and its configuration.
32+
- **Dockerfile** - Assembles an image containing the ACAP Native SDK and builds the application using it.
33+
- **README.md** - Step-by-step instructions on how to run the example.
34+
35+
### Supported devices
36+
37+
- ARTPEC-9, ARTPEC-8, and ARTPEC-7 based cameras and other video devices.
38+
39+
## Build the application
40+
41+
Standing in your working directory, run the following commands:
42+
43+
> [!NOTE]
44+
>
45+
> Depending on the network your local build machine is connected to, you may need to add proxy
46+
> settings for Docker. See
47+
> [Proxy in build time](https://developer.axis.com/acap/develop/proxy/#proxy-in-build-time).
48+
49+
```sh
50+
docker build --platform=linux/amd64 --tag <APP_IMAGE> --build-arg ARCH=<ARCH> .
51+
```
52+
53+
- `<APP_IMAGE>` is the name to tag the image with, e.g., `axoverlay2:1.0`
54+
- `<ARCH>` is the architecture of the camera you are using, e.g., `armv7hf` (default) or `aarch64`
55+
56+
Copy the result from the container image to a local directory called `build`:
57+
58+
```sh
59+
docker cp $(docker create --platform=linux/amd64 <APP_IMAGE>):/opt/app ./build
60+
```
61+
62+
The `build` directory contains the build artifacts, where the ACAP application
63+
is found with suffix `.eap`, depending on which SDK architecture that was
64+
chosen, one of these files should be found:
65+
66+
- `Axoverlay2_example_application_1_0_0_aarch64.eap`
67+
- `Axoverlay2_example_application_1_0_0_armv7hf.eap`
68+
69+
> [!NOTE]
70+
>
71+
> For detailed information on how to build, install, and run ACAP applications, refer to the official ACAP documentation: [Build, install, and run](https://developer.axis.com/acap/develop/build-install-run/).
72+
73+
## Install and start the application
74+
75+
Browse to the application page of the Axis device:
76+
77+
```sh
78+
http://<AXIS_DEVICE_IP>/index.html#apps
79+
```
80+
81+
1. Click on the tab **Apps** in the device GUI
82+
2. Enable the **Allow unsigned apps** toggle
83+
3. Click the **(+ Add app)** button to upload the application file
84+
4. Select the newly built application package, depending on architecture:
85+
86+
- `Axoverlay2_example_application_1_0_0_aarch64.eap`
87+
- `Axoverlay2_example_application_1_0_0_armv7hf.eap`
88+
89+
5. Click **Install**
90+
6. Run the application by enabling the **Start** switch.
91+
92+
## Expected output
93+
94+
<img alt='A green smiley face superimposed on a picture of a roof' src="screenshot.jpg" width="500">
95+
96+
While the application is running, a rotating and colour-shifting icon should appear in the top-left
97+
corner of video streams.
98+
99+
The application log can be found directly at:
100+
101+
```sh
102+
http://<AXIS_DEVICE_IP>/axis-cgi/admin/systemlog.cgi?appname=axoverlay2
103+
```
104+
105+
During normal operation, the application prints log entries for each connecting and disconnecting
106+
video stream:
107+
108+
```text
109+
axoverlay2[2095]: Created overlay 1 on stream 1041, stream_size=3840x2160 overlay_used_size=135x135 overlay_full_size=136x136
110+
axoverlay2[2095]: Removed overlay 1 from stream 1041
111+
```
112+
113+
In addition, the code contains some debug prints which may be enabled using the DEBUG flag found in
114+
axoverlay2.c.
115+
116+
## License
117+
118+
**[MIT](../LICENSE)**

‎axoverlay2/app/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/build

‎axoverlay2/app/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Axis Communications AB
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎axoverlay2/app/Makefile‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
PROG1 = $(shell jq -r '.acapPackageConf.setup.appName' manifest.json)
2+
3+
PKGS = gio-2.0 glib-2.0 cairo vdostream axoverlay2
4+
CFLAGS += $(shell pkg-config --cflags $(PKGS))
5+
LDLIBS += $(shell pkg-config --libs $(PKGS)) -lm
6+
7+
CFLAGS += -Wall \
8+
-Wextra \
9+
-Wformat=2 \
10+
-Wpointer-arith \
11+
-Wbad-function-cast \
12+
-Wstrict-prototypes \
13+
-Wmissing-prototypes \
14+
-Winline \
15+
-Wdisabled-optimization \
16+
-Wfloat-equal \
17+
-W \
18+
-Werror
19+
20+
all: axoverlay2
21+
22+
$(PROG1): $(PROG1).c
23+
mkdir -p debug
24+
$(CC) $^ $(CFLAGS) $(LDFLAGS) $(LDLIBS) -o debug/$@
25+
cp debug/$@ .
26+
$(STRIP) $@
27+
28+
.PHONY: clean
29+
clean:
30+
rm -rf $(PROG1) *.o *.eap* *_LICENSE.txt package.conf* param.conf tmp* debug

0 commit comments

Comments
 (0)