flutter_device_orientation #

A Flutter package for calculating the Earth-relative direction in which a phone's rear camera is pointing. It is intended for sky maps, astronomy apps, camera-direction interfaces, and similar sensor-based experiences.

The package exposes:

• yaw: camera azimuth, normalized to 0 <= yaw < 360 degrees.
• pitch: camera altitude, in the range -90 <= pitch <= 90 degrees.
• roll: signed phone rotation around the camera/viewing axis, approximately -180 to +180 degrees.

Conventions #

Yaw and pitch describe the camera direction directly. A sky map should not need to combine them with roll to determine where the camera is pointing.

How it works #

flutter_device_orientation combines raw accelerometer and magnetometer data from sensors_plus. It constructs an East/North/Up basis, treats the rear camera as approximately the device's negative Z axis, and derives camera azimuth, altitude, and roll from that 3D orientation.

It does not require an Android rotation-vector sensor and does not use a compass heading as the final camera yaw. Sensor availability and accuracy still depend on the physical device, calibration, motion, and magnetic environment.

Azimuth is mathematically undefined while the camera points almost straight up or down. Near pitch = +/-90°, small sensor changes can therefore cause large yaw changes.

Installation #

flutter pub add flutter_device_orientation

Then import the package:

import 'package:flutter_device_orientation/flutter_device_orientation.dart';

Usage #

final deviceOrientation = DeviceOrientation();

final subscription = deviceOrientation.stream.listen((orientation) {
  final azimuth = orientation.yaw;
  final altitude = orientation.pitch;
  final roll = orientation.roll;

  print('azimuth=$azimuth altitude=$altitude roll=$roll');
});

deviceOrientation.start();

// Later:
await subscription.cancel();
deviceOrientation.dispose();

The latest value is also available synchronously through deviceOrientation.data. It is OrientationData.zero until the first valid accelerometer/magnetometer pair has been processed.

See the example application for a Flutter UI that displays all three angles.

Platform notes #

The underlying sensor plugin supports mobile and other platforms to differing degrees. Test on the physical target devices, particularly for applications that depend on magnetic accuracy. Nearby metal, magnets, and device calibration can affect readings.

License #

MIT. See LICENSE.