|
| 1 | +# Example05Camera - Camera Animations |
| 2 | + |
| 3 | +This example demonstrates smooth camera animations in OpenMapView, showing how to animate map position and zoom level changes with customizable durations and completion callbacks. |
| 4 | + |
| 5 | +## Features Demonstrated |
| 6 | + |
| 7 | +- Animated camera movements to specific locations |
| 8 | +- Smooth zoom animations (zoom in/out) |
| 9 | +- Different animation durations (fast: 500ms, normal: 1000ms, slow: 2000ms) |
| 10 | +- Animation completion callbacks (onFinish, onCancel) |
| 11 | +- Animation cancellation with stopAnimation() |
| 12 | +- Multiple markers as animation targets |
| 13 | + |
| 14 | +## Screenshot |
| 15 | + |
| 16 | + |
| 17 | + |
| 18 | +## Quick Start |
| 19 | + |
| 20 | +### Option 1: Run in Android Studio |
| 21 | + |
| 22 | +1. Open the OpenMapView project in Android Studio |
| 23 | +2. Select `examples.Example05Camera` from the run configuration dropdown |
| 24 | +3. Click Run (green play button) |
| 25 | +4. Deploy to device or emulator |
| 26 | + |
| 27 | +### Option 2: Build and Install from Command Line |
| 28 | + |
| 29 | +```bash |
| 30 | +# From project root - build, install, and launch |
| 31 | +./gradlew :examples:Example05Camera:installDebug |
| 32 | + |
| 33 | +# Launch the app |
| 34 | +adb shell am start -n de.afarber.openmapview.example05camera/.MainActivity |
| 35 | +``` |
| 36 | + |
| 37 | +## Code Highlights |
| 38 | + |
| 39 | +### Animating to a Specific Location with Zoom |
| 40 | + |
| 41 | +```kotlin |
| 42 | +mapView.animateCamera( |
| 43 | + CameraUpdateFactory.newLatLngZoom(targetLocation, 15.0), |
| 44 | + 1000, // 1 second duration |
| 45 | + object : OnCameraAnimationListener { |
| 46 | + override fun onFinish() { |
| 47 | + Toast.makeText(context, "Animation finished", Toast.LENGTH_SHORT).show() |
| 48 | + } |
| 49 | + override fun onCancel() { |
| 50 | + Toast.makeText(context, "Animation cancelled", Toast.LENGTH_SHORT).show() |
| 51 | + } |
| 52 | + } |
| 53 | +) |
| 54 | +``` |
| 55 | + |
| 56 | +### Animating Zoom In/Out |
| 57 | + |
| 58 | +```kotlin |
| 59 | +// Zoom in with 500ms animation |
| 60 | +mapView.animateCamera( |
| 61 | + CameraUpdateFactory.zoomIn(), |
| 62 | + 500 |
| 63 | +) |
| 64 | + |
| 65 | +// Zoom out with 500ms animation |
| 66 | +mapView.animateCamera( |
| 67 | + CameraUpdateFactory.zoomOut(), |
| 68 | + 500 |
| 69 | +) |
| 70 | +``` |
| 71 | + |
| 72 | +### Stopping an Animation |
| 73 | + |
| 74 | +```kotlin |
| 75 | +// Cancel any running animation |
| 76 | +mapView.stopAnimation() |
| 77 | +``` |
| 78 | + |
| 79 | +### Move Camera Instantly (No Animation) |
| 80 | + |
| 81 | +```kotlin |
| 82 | +// Jump to location immediately without animation |
| 83 | +mapView.moveCamera( |
| 84 | + CameraUpdateFactory.newLatLngZoom(location, 14.0) |
| 85 | +) |
| 86 | +``` |
| 87 | + |
| 88 | +## Key Concepts |
| 89 | + |
| 90 | +### CameraUpdateFactory |
| 91 | + |
| 92 | +Factory for creating camera update operations: |
| 93 | + |
| 94 | +- `newLatLng(LatLng)` - Move to location, keep current zoom |
| 95 | +- `newLatLngZoom(LatLng, Double)` - Move to location with specific zoom |
| 96 | +- `newCameraPosition(CameraPosition)` - Full control over camera state |
| 97 | +- `zoomIn()` - Increment zoom by 1 |
| 98 | +- `zoomOut()` - Decrement zoom by 1 |
| 99 | +- `zoomTo(Double)` - Set specific zoom level |
| 100 | +- `zoomBy(Double)` - Adjust zoom by amount (positive or negative) |
| 101 | + |
| 102 | +### animateCamera() Overloads |
| 103 | + |
| 104 | +```kotlin |
| 105 | +// Default 250ms duration, no callback |
| 106 | +animateCamera(cameraUpdate) |
| 107 | + |
| 108 | +// Custom duration, no callback |
| 109 | +animateCamera(cameraUpdate, durationMs) |
| 110 | + |
| 111 | +// Custom duration with callback |
| 112 | +animateCamera(cameraUpdate, durationMs, listener) |
| 113 | +``` |
| 114 | + |
| 115 | +### OnCameraAnimationListener |
| 116 | + |
| 117 | +Callback interface for animation lifecycle: |
| 118 | + |
| 119 | +- `onFinish()` - Called when animation completes normally |
| 120 | +- `onCancel()` - Called when animation is interrupted by stopAnimation() or new animation |
| 121 | + |
| 122 | +### moveCamera vs animateCamera |
| 123 | + |
| 124 | +- `moveCamera()` - Instant camera update, no animation |
| 125 | +- `animateCamera()` - Smooth interpolated transition |
| 126 | + |
| 127 | +## What to Test |
| 128 | + |
| 129 | +1. Location Buttons - Click "Loc 1", "Loc 2", "Loc 3" to animate to different markers |
| 130 | +2. Different Durations - Notice Location 3 uses 2 second animation (slower) |
| 131 | +3. Zoom Controls - Use + and - buttons for smooth zoom animations |
| 132 | +4. Callbacks - Location 1 shows toast messages on animation finish/cancel |
| 133 | +5. Stop Button - Click during animation to cancel and see onCancel callback |
| 134 | +6. Sequential Animations - Start animation, then immediately click another location (first animation cancels) |
| 135 | + |
| 136 | +## Animation Details |
| 137 | + |
| 138 | +This example sets up three marker locations around Bochum, Germany: |
| 139 | + |
| 140 | +| Location | Coordinates | Animation Duration | Callbacks | |
| 141 | +| -------- | ----------- | ------------------ | --------- | |
| 142 | +| Location 1 | (51.4700, 7.2400) | 1000ms | Yes (toast) | |
| 143 | +| Location 2 | (51.4620, 7.2600) | 1000ms | No | |
| 144 | +| Location 3 | (51.4550, 7.2350) | 2000ms | No | |
| 145 | + |
| 146 | +## Technical Details |
| 147 | + |
| 148 | +### Animation Implementation |
| 149 | + |
| 150 | +- Uses Kotlin coroutines for smooth frame-by-frame updates |
| 151 | +- Linear interpolation between start and end positions |
| 152 | +- 60 FPS target (16ms frame delay) |
| 153 | +- Automatically handles map tile loading during animation |
| 154 | +- Lifecycle-aware: animations cancelled when activity destroyed |
| 155 | + |
| 156 | +### Lifecycle Integration |
| 157 | + |
| 158 | +- Animations run in MapController's coroutine scope |
| 159 | +- Automatic cleanup via existing lifecycle hooks |
| 160 | +- No memory leaks when activity is destroyed |
| 161 | +- onDestroy() cancels all running animations |
| 162 | + |
| 163 | +### Performance |
| 164 | + |
| 165 | +- Efficient coroutine-based implementation |
| 166 | +- Minimal CPU usage during animation |
| 167 | +- Smooth rendering on all supported devices |
| 168 | +- Tile downloads continue during animation |
| 169 | + |
| 170 | +## Advanced Usage |
| 171 | + |
| 172 | +### Custom Animation Duration Based on Distance |
| 173 | + |
| 174 | +```kotlin |
| 175 | +val distance = calculateDistance(currentPosition, targetPosition) |
| 176 | +val duration = (distance * 100).toInt().coerceIn(500, 3000) |
| 177 | + |
| 178 | +mapView.animateCamera( |
| 179 | + CameraUpdateFactory.newLatLng(targetPosition), |
| 180 | + duration |
| 181 | +) |
| 182 | +``` |
| 183 | + |
| 184 | +### Chain Animations with Callbacks |
| 185 | + |
| 186 | +```kotlin |
| 187 | +mapView.animateCamera( |
| 188 | + CameraUpdateFactory.newLatLng(location1), |
| 189 | + 1000, |
| 190 | + object : OnCameraAnimationListener { |
| 191 | + override fun onFinish() { |
| 192 | + // Start second animation when first completes |
| 193 | + mapView.animateCamera( |
| 194 | + CameraUpdateFactory.zoomIn(), |
| 195 | + 500 |
| 196 | + ) |
| 197 | + } |
| 198 | + override fun onCancel() { |
| 199 | + // Handle cancellation |
| 200 | + } |
| 201 | + } |
| 202 | +) |
| 203 | +``` |
| 204 | + |
| 205 | +### Animate to Show All Markers (Future Feature) |
| 206 | + |
| 207 | +```kotlin |
| 208 | +// This will be available in future versions |
| 209 | +val bounds = LatLngBounds.builder() |
| 210 | + .include(marker1.position) |
| 211 | + .include(marker2.position) |
| 212 | + .include(marker3.position) |
| 213 | + .build() |
| 214 | + |
| 215 | +mapView.animateCamera( |
| 216 | + CameraUpdateFactory.newLatLngBounds(bounds, padding) |
| 217 | +) |
| 218 | +``` |
| 219 | + |
| 220 | +## Next Steps |
| 221 | + |
| 222 | +- Try [Example01Pan](../Example01Pan) for basic map panning |
| 223 | +- Try [Example02Zoom](../Example02Zoom) for zoom controls |
| 224 | +- Try [Example03Markers](../Example03Markers) for marker overlays |
| 225 | +- Try [Example04Polylines](../Example04Polylines) for vector shapes |
| 226 | +- Experiment with different animation durations |
| 227 | +- Add your own markers and create navigation sequences |
| 228 | + |
| 229 | +## Map Location |
| 230 | + |
| 231 | +Default Center: Bochum, Germany (51.4620°N, 7.2480°E) at zoom 13.0 |
| 232 | + |
| 233 | +All three marker locations are positioned around Bochum within approximately 2km radius. |
0 commit comments