Getting Started with Spectra

2. Platform-Specific Setup

sudo apt install build-essential cmake git \
    libvulkan-dev libglfw3-dev glslang-tools

xcode-select --install
brew install cmake vulkan-headers \
    vulkan-loader glslang molten-vk

3. Build from Source

git clone https://github.com/danlil240/Spectra.git
cd Spectra
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

Makefile Shortcuts

4. CMake Options

cmake -B build \
    -DCMAKE_BUILD_TYPE=Release \
    -DSPECTRA_BUILD_TESTS=ON \
    -DSPECTRA_BUILD_EXAMPLES=ON \
    -DSPECTRA_BUILD_GOLDEN_TESTS=ON \
    -DSPECTRA_USE_FFMPEG=ON

Build Targets

5. First Plot (C++)

#include <spectra/easy.hpp>

int main() {
    spectra::plot({0.f, 1.f, 2.f, 3.f, 4.f},
                  {0.f, 1.f, 0.5f, 1.5f, 2.f}, "c-o");
    spectra::title("First Spectra Plot");
    spectra::show();
}

Or use the full object API for maximum control:

#include <spectra/spectra.hpp>

int main() {
    spectra::App app;
    auto& fig = app.figure({.width = 1280, .height = 720});
    auto& ax  = fig.subplot(1, 1, 1);

    ax.line(x, y).label("signal").color(spectra::rgb(0.2f, 0.8f, 1.0f));
    ax.title("Sensor Data");
    ax.xlabel("Time (s)");
    ax.ylabel("Amplitude");

    fig.show();
}

Run an Example

# Linux / macOS
./build/examples/basic_line
./build/examples/easy_api_demo
./build/examples/demo_3d

# Windows
.\build\examples\Release\basic_line.exe

6. Python Quick Start

# Install
pip install spectra-plot

# Or development install from source
cd python && pip install -e ".[dev]"

The Python package (spectra-plot) communicates with the spectra-backend daemon over Unix sockets. The backend is auto-launched on first connection.

Python IPC sequence

Session lifecycle from socket connect through figure creation, series updates, and GPU render.

Diagram gallery

import spectra as sp
sp.plot([1, 4, 9, 16, 25])
sp.show()

7. Eigen Integration

Spectra accepts Eigen vectors directly — no conversions needed. Build with -DSPECTRA_USE_EIGEN=ON (requires Eigen3 headers).

#include <spectra/eigen_easy.hpp>

Eigen::VectorXf x = Eigen::VectorXf::LinSpaced(100, 0, 2 * M_PI);
Eigen::VectorXf y = x.array().sin();

spectra::plot(x, y, "r--o");  // zero-copy, direct Eigen support
spectra::show();

8. CMake Integration (Downstream Projects)

After installing Spectra (cmake --install build), use it from your project:

find_package(spectra 0.1 REQUIRED)
target_link_libraries(myapp PRIVATE spectra::spectra)

9. Deployment & Packaging

APT Repository (Ubuntu 22.04 / 24.04)

The recommended Linux install — adds the Spectra repo so apt handles updates automatically:

# Import the signing key
curl -fsSL https://danlil240.github.io/Spectra/apt/spectra-archive-keyring.asc \
  | sudo gpg --dearmor -o /etc/apt/keyrings/spectra.gpg

# Add the repository (auto-detects your Ubuntu codename)
echo "deb [signed-by=/etc/apt/keyrings/spectra.gpg] https://danlil240.github.io/Spectra/apt $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/spectra.list

# Install
sudo apt update
sudo apt install spectra

Install from Source

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
sudo cmake --install build --prefix /usr/local

This installs headers to include/spectra/, libraries to lib/, binaries (spectra-backend, spectra-window) to bin/, and fonts/icons to share/spectra/.

Runtime Dependencies by Artifact

CPack Packages

Additional Package Formats

pip install build
python -m build

brew install spectra

10. Docker

# Full deployment test
./docker/ubuntu22/run_tests.sh

# With GPU tests
RUN_GPU_TESTS=1 ./docker/ubuntu22/run_tests.sh

# Docker Compose
cd docker && docker compose up --build spectra-xvfb

11. Testing

cmake -B build -DSPECTRA_BUILD_TESTS=ON -DSPECTRA_BUILD_GOLDEN_TESTS=ON
cmake --build build -j$(nproc)
cd build && ctest --output-on-failure

Running Specific Tests

# Single test suite
cd build && ./tests/unit/unit_test_math3d

# Pattern match
ctest -R "3d" --output-on-failure

# Benchmarks
./tests/bench/bench_3d

# Python tests
cd python && pytest tests/ -v

# Sanitizers
cmake -B build-asan -DCMAKE_CXX_FLAGS="-fsanitize=address -fno-omit-frame-pointer"
cmake --build build-asan && cd build-asan && ctest --output-on-failure

12. CI/CD

Continuous Integration

Every push and PR triggers (.github/workflows/ci.yml):

Release Pipeline

Triggered on v* tag push (.github/workflows/release.yml):

1. package-linux — .deb, .rpm, .tar.gz, AppImage
2. package-macos — .tar.gz for ARM64
3. package-windows — .zip with Vulkan SDK
4. python-wheels — via cibuildwheel for Linux/macOS/Windows × Python 3.9–3.13
5. python-sdist — Source distribution
6. release — GitHub Release with all artifacts, publishes to PyPI

# Trigger a release
git tag v0.1.0 && git push origin v0.1.0

Verify Installation

cd build && ctest --output-on-failure
vulkaninfo --summary

Where Next?