Aniray

Aniray is a library for animating and orchestrating large arrays of emitters, actuators, displays, and more.

NOTE: This library is under active development and is currently prone to large breaking changes. Following the first release Aniray will conform to semantic versioning.

Principles

• Large Installation Focused: Aniray is a one-stop solution for large systems individual parts. Object placement and hardware configuration are configured separately from the code so that they may change freely as projects change during development.
• Visualization Independent: Many installations of lights and actuators don't include a screen output. Aniray is not built specifically for any other graphics toolkit (i.e. Cinder or openFrameworks). These frameworks may be used alongside Aniray but are not required.
• Standards Driven, Hardware Independent: Exact hardware components vary from project to project, and sometimes original parts aren't available when repairs are necessary. Rather than picking specific or proprietary products, this library aims to use broadly-supported standards that allow for the most flexibility.
• Abstracted and Extensible: Most C++ classes in Aniray that provide support for a particular function or task are extended from broader base classes. This promotes user extensibility of Aniray and open source contribution to the library.
• Time-based Processing: Tasks are performed in reference to time, not frames. This allows for a consistent experience across hardware platforms of varying processing power. If a machine is not up to the task, then it will be immediately obvious instead of slowing down.
• Open Source for Unrestricted Use: Aniray promotes the idea that the technical tools and resources to create art should be free and open (with attribution) while understanding that creative and artistic practice may remain proprietary to the artist. Aniray aims to separate the technical boilerplate from the creative process and lower the bar to enter the creative process. Aniray does not depend on resources that require open sourcing the creative code.

Key Terminology

• Node: A Node is a control point in an installation in physical space. This may be a LED pixel, an actuator assembly, some other output device, or a combination of these. For example, in a series of winches that move up and down each winch is a Node with a vertical axis control. If there are lights at the end of the winches, then the combination of the light and winch is still one Node (where the node has a vertical position and color outputs). If there are lights not specific to each winch, then these would be separate Nodes. Nodes may be tied to a physical output or used virtually in animations to inform physical Nodes.
• Node Array: A Node Array is group of Nodes. A Node Array can be initialized from a list of positions and addresses. A Node Array can also be generated by creating a dense 3D grid around another Node Array.
• Node Array Output: A Node Array Output ties a Node Array to a physical output device.
• Node Array Sampler: A Node Array Sampler allows for sampling values from a dense Node Array to inform a less-dense Node Array. The sampling mapping can be found automatically by distance or can be defined statically.
• IO Interface: An IO Interface is an interface to inputs and outputs to the application. These can be discrete, counters, integers, etc.

Features

• Automatic subsampling node grid generation and caching
• Load node physical data from CSV
• Visualization framework independent (can be used with Cinder, oFx, etc.)
• Open Lighting Architecture (OLA) for lighting output allowing for robust many universe outputs of E1.31 (sACN), Artnet, KiNET, USB DMX adapters, and more.
• Extensible output classes for other output methods
• Modbus support receiving inputs separate from nodes
• Extensible IO classes for other input and output methods
• Threaded runners for receiving inputs and sending frames at fixed rates
• Boost Geometry types for graphics-independent transformations
• Templated data structs and output transformations for nodes

Planned Features

• Node-specific animation queues
• Thorough Doxygen documentation
• Thread safety for all methods, not just methods always used in threads

Requirements

• Only tested on Linux, but may work on other platforms
• C++17
• clang or gcc, untested on other platforms
• Boost >= 1.74.0 (Boost Software License)
• OpenSSL >= 1.1.0 (OpenSSL License)
• libola >= 0.10.8 (LGPL) or turn off with -DANIRAY_WITHOUT_OLA=ON and bring or contribute your own output
• libmodbus >= 3.1.6 (LGPL) or turn off with -DANIRAY_WITHOUT_MODBUS=ON and or contribute bring your own IO
• Bundled requirements (Git submodules):
  • ben-strasser/fast-cpp-csv-parser (BSD-3-Clause License)

Build and Lint Requirements

• CMake
• pkg-config
• iwyu >= 0.15 (include-what-you-use) with -DANIRAY_WITH_LINT=ON
• clang-tidy >= 13.0.0 with -DANIRAY_WITH_LINT=ON

Using

1. Install required dependencies above
2. Clone with submodules

   git clone --recursive https://github.com/HypersonicED/aniray.git

3. Either:
   • Add to your CMakeLists.txt
   • Build the static library

     cmake -H. -B_builds/Release -DCMAKE_BUILD_TYPE=Release

   • Build the shared library (NOTE: This is not usually useful due to templated types)

     cmake -H. -B_builds/Release -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON

License Notice

Copyright (c) 2022 Hypersonic
Copyright (c) 2022 Perry Naseck
All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

A copy of the Apache 2.0 license may also be found in the LICENSE file in the
root directory of this source tree.

SPDX-License-Identifier: Apache-2.0