tilt_alignment_scale

A customizable, sensor-driven alignment scale with a moving ball (bubble) for horizontal or vertical guidance. Built for Flutter apps that need an on-screen level/alignment guide without camera dependencies.

Features:

• Horizontal or vertical scale
• Moving ball driven by device tilt (roll for horizontal, pitch for vertical)
• Configurable ball size and colors
• Optional tick marks, center line, and degree-based guide lines (e.g., 15°, 35°)
• Threshold-based ball color zones (change color when crossing degrees)
• Smooth motion with low-pass filtering

This package uses sensors_plus for accelerometer data only (no camera).

Quick Start

import 'package:flutter/material.dart';
import 'package:tilt_alignment_scale/tilt_alignment_scale.dart';

class DemoPage extends StatelessWidget {
  const DemoPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.black,
      body: Center(
        child: AlignmentScale(
          config: AlignmentScaleConfig(
            axis: Axis.horizontal,
            ballSize: 28,
            defaultBallColor: Colors.blue,
            angleRangeDegrees: 60,
            showTicks: true,
            showCenterLine: true,
            showGuideLines: true,
            guideLineDegrees: const <double>[15, 35],
            angleColorZones: const <AngleColorZone>[
              AngleColorZone(minAbsDegrees: 0, ballColor: Colors.green),
              AngleColorZone(minAbsDegrees: 15, ballColor: Colors.orange),
              AngleColorZone(minAbsDegrees: 35, ballColor: Colors.red),
            ],
            scaleSize: const Size(340, 80),
          ),
          onAngleUpdate: (double angle, bool inRange) {
            // angle in degrees, inRange true if within first guideLine threshold
          },
        ),
      ),
    );
  }
}

Configuration

Use AlignmentScaleConfig to adjust:

• axis: Axis.horizontal or Axis.vertical
• ballSize: double
• defaultBallColor: Color
• angleColorZones: list of (minAbsDegrees, ballColor) to change color beyond thresholds
• angleRangeDegrees: max absolute angle mapped to scale ends
• showTicks, tickDivisions, showCenterLine
• showGuideLines, guideLineDegrees
• scaleSize, scaleBackgroundColor, scaleBorderRadius
• lineOpacity, smoothingFactor

Example App

See the example/ folder for a minimal app demonstrating both orientations and color changes.

License

MIT