Skip to main content

flutter_globe_3d 3.0.0 copy "flutter_globe_3d: ^3.0.0" to clipboard
flutter_globe_3d: ^3.0.0 copied to clipboard

High-performance interactive 3D sphere rendering for Flutter, with shader materials, camera poses, annotations and connections.

Flutter Sphere 3D #

pub package License: MIT

High-performance interactive 3D spheres for Flutter. A GPU fragment shader draws the textured sphere; Flutter widgets remain interactive as surface markers or arranged annotations. The API also includes a camera pose system, animated focus, automatic spin, lighting, atmosphere and curved connections.

Version 3.0 is a deliberate breaking redesign. The package name remains flutter_globe_3d, while the public API is now consistently Sphere*. Existing 2.x applications can stay on their current version until they migrate.

Install #

dependencies:
  flutter_globe_3d: ^3.0.0

Flutter 3.44 or newer is required.

Quick start #

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

class InteractiveSphere extends StatefulWidget {
  const InteractiveSphere({super.key});

  @override
  State<InteractiveSphere> createState() => _InteractiveSphereState();
}

class _InteractiveSphereState extends State<InteractiveSphere> {
  late final controller = SphereController();

  static const shanghai = SphereCoordinate(
    latitude: 31.2304,
    longitude: 121.4737,
  );

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => SizedBox(
        width: 360,
        height: 360,
        child: SphereView.earth(
          controller: controller,
          nodes: [
            SphereNode.annotation(
              id: 'shanghai',
              coordinate: shanghai,
              child: TextButton(
                onPressed: () => controller.camera.focus(
                  target: shanghai,
                  view: const SphereViewAngle.upperLeft(tiltDegrees: 60),
                  zoom: 2,
                ),
                child: const Text('Shanghai'),
              ),
            ),
          ],
        ),
      );
}

SphereView.earth() uses the bundled day and night textures. For your own equirectangular color map, use SphereView(texture: ...); night texture is optional. Texture providers can be replaced while the widget remains mounted.

3.0 API at a glance #

  • SphereView: declarative texture, quality, lighting, glow, gestures, node and connection configuration.
  • SphereController.camera: pose commands, zoom, state snapshots and awaitable animation results.
  • SphereController.spin: explicit start/stop/configure controls; default speed is 1.5 degrees per second and spin starts stopped.
  • SphereCoordinate, SphereViewAngle, SphereCameraPose, SphereVector3: named geographic values and right-handed XYZ camera values.
  • SphereNode.surface, .annotation, .denseAnnotation: interactive Flutter widgets associated with geographic anchors.
  • SphereConnection: stable-ID arcs with optional animated dashes and directional arrows.

The world axes are +Y north, +Z longitude 0°, and +X longitude 90° east. Coordinates and camera angles use degrees; zoom is bounded by SphereCameraLimits.

The optional, standalone shader-canvas demo is exported separately from package:flutter_globe_3d/flutter_globe_3d_shader.dart (UnifiedShaderCanvas and the historical GirdShader spelling). It is not part of the sphere camera or material API.

Documentation #

  • Usage guide: camera recipes, scene construction, materials, lifecycle and performance.
  • 3.0 migration guide: breaking changes and old-to-new API mappings.
  • API architecture and design: public API responsibilities, coordinate semantics, animation outcomes and performance contracts.
  • Roadmap: planned capabilities, including Flutter widgets rendered directly onto the sphere surface.
  • Changelog: 3.0 changes and historical release notes.

The complete public reference is generated from Dart documentation comments; pub.dev builds and hosts it when a package version is published. To generate it locally, run dart doc from the package root.

Example #

Run the interactive showcase:

cd example
flutter run

It demonstrates camera focus and overview, a 60° upper-left view, roll, three node placements, interactive labels, connections, quality, lighting, glow, live texture replacement, automatic spin and opt-in spin resumption after focus.

See example/README.md and texture source credits for details.

Verify a release #

From the package root:

flutter analyze
flutter test
cd example
flutter analyze
flutter test

dart doc --dry-run . checks the generated API reference. Run flutter pub publish --dry-run immediately before publishing from a clean working tree.

License #

MIT. See LICENSE.

9
likes
0
points
464
downloads

Publisher

verified publisherliliin.icu

Weekly Downloads

High-performance interactive 3D sphere rendering for Flutter, with shader materials, camera poses, annotations and connections.

Repository (GitHub)
View/report issues

License

unknown (license)

Dependencies

flutter, vector_math

More

Packages that depend on flutter_globe_3d