Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,23 @@
## 1.3.0 (unreleased)

### Breaking behavior

- Polyline animations now pause when the app goes to the background and go on from the same place when it returns. Use `pauseInBackground: false` on `MapAnimationController` to keep the old behavior.
- When the system asks to reduce motion, polylines are drawn as they are and markers move at once. Use `respectReduceMotion: false` to keep animating.

### New

- `PulseAnimator`: a light that travels along a dimmed copy of the route (extra polyline `<id>#glow`).
- `DashFlowAnimator`: dashes that flow along the route. Its limitation (pattern in pixels, cut in meters) is documented.
- `AnimatedPolyline.segmented` and `RouteSegment`: a route in several colors, with the animator applied to the whole route.
- `MapAnimationController.followCamera(CameraFollow(...))`, `stopFollowingCamera()` and `onCameraMoveStarted()` to follow a marker with the camera and stop when the user moves the map.
- `PolylineAnimator.animateAll` and `PolylineAnimator.reducedMotionFrame` for animations made of several polylines.
- `MapAnimationController.pauseInBackground` and `respectReduceMotion`.

### Other

- An animation without duration is drawn at once and redrawn when its polyline changes.

## 1.2.0 (unreleased)

### Breaking behavior
Expand All @@ -11,8 +31,14 @@
- `MapAnimationController.markerAnimationMode`: `MarkerAnimationMode.queue` (default, as before) or `MarkerAnimationMode.latestOnly`, which goes straight to the newest position from where the marker is shown and drops the ones in between.
- `MapAnimationController.markerDuration`: `MarkerDuration.fixed(duration)` or `MarkerDuration.adaptive(max: duration)`, where each move lasts as long as the time between positions. `markersAnimationDuration` still works and is a shortcut for `fixed`.

- Vehicle tracking: `MapAnimationController.trackVehicle(VehicleTracking(...))`, `updateVehicle(position)` and `stopTrackingVehicle(markerId)`. Positions are put on the route (searching around the last known distance first, so crossing routes and parallel streets do not cause jumps), the route is drawn as travelled and remaining (`RouteStyle`), `followRoute` makes the marker follow the route and turn at the corners, and `onOffRoute` reports positions beyond `snapToleranceMeters`.
- Animation control: `MapAnimationController.polylineAnimation(id)` returns a `PolylineAnimationHandle` with `pause()`, `resume()`, `seek(progress)`, `isPlaying`, `isCompleted`, `value`, a `progress` stream, `onComplete` and `onCycle`.
- `PolylineCodec.decode` and `PolylineCodec.encode` for the Google Encoded Polyline format, with precision 5 or 6.
- `MapAnimationUtils.boundsOf(points)`.

### Other

- Polyline animations now run on their own simulation, with the same timing as before, so they can be paused and resumed at any point.
- All markers share one ticker and the changes of a frame go to the map together. With 50 markers it is one map call per frame, as before, at about 170 µs per frame in the test harness.

## 1.1.0
Expand Down
137 changes: 137 additions & 0 deletions README.es.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,8 @@ Todos comparten estas opciones: `duration`, `curve`, `repeat`, `repeatCount`, `r
| `SnackAnimator` | Dibuja la línea de inicio a fin y luego la borra en el mismo sentido. |
| `FadeInProgressiveAnimator` | Hace aparecer la línea durante el primer 30 % y luego la borra desde el inicio. |
| `ColorTransitionAnimation` | Cambia el color de forma suave a través de una lista de `colors`. |
| `PulseAnimator` | Una luz recorre una copia atenuada de la ruta, para una espera de «buscando conductor». También dibuja una polyline con el ID `<id>#glow`. |
| `DashFlowAnimator` | Una línea punteada cuyos tramos avanzan por la ruta. Mira su limitación más abajo. |

## Crea tu propio animator

Expand Down Expand Up @@ -187,6 +189,141 @@ mapAnimationController = MapAnimationController(

Cada marcador se mueve con su propio reloj, así que uno lento no frena a los demás.

## Sigue a un vehículo por una ruta

Para un viaje o una entrega ya tienes la ruta. Pásasela al controlador junto con el marcador del vehículo y envía cada posición del GPS a `updateVehicle`. La posición se ajusta a la ruta, así el marcador no se sale de la calle, y la ruta se dibuja como la parte ya recorrida y la parte que falta.

```dart
mapAnimationController.trackVehicle(
VehicleTracking(
markerId: const MarkerId('driver'),
route: puntosDeLaRuta, // por ejemplo, decodificados de una respuesta de Directions
traveled: const RouteStyle(color: Colors.grey),
remaining: const RouteStyle(color: Colors.blue, width: 6),
snapToleranceMeters: 30,
followRoute: true,
onOffRoute: (posicion) => pedirNuevaRuta(posicion),
),
);

// En cada actualización del GPS:
mapAnimationController.updateVehicle(posicion);

// Cuando termina el viaje:
mapAnimationController.stopTrackingVehicle(const MarkerId('driver'));
```

| Opción | Qué hace | Por defecto |
| --- | --- | --- |
| `snapToleranceMeters` | Qué tan lejos de la ruta puede estar una posición y aun así ajustarse a ella. | 30 |
| `followRoute` | El marcador toma la ruta entre dos posiciones y gira en las esquinas, en lugar de ir en línea recta. | `false` |
| `consumeRoute` | Dibuja la parte recorrida con `traveled` (o la oculta con `visible: false`) y el resto con `remaining`. Con `false`, toda la ruta conserva el estilo `remaining`. | `true` |
| `onOffRoute` | Se llama con una posición más lejos que la tolerancia. El marcador va a esa posición tal cual y se conserva el avance en la ruta. | ninguno |

- El marcador se crea al inicio de la ruta si no existe. Mientras el vehículo está en seguimiento, `updateMarkers` no lo mueve ni lo elimina.
- Las dos líneas son polylines con los IDs `<markerId>#traveled` y `<markerId>#remaining`. No uses esos IDs para otras polylines.
- La búsqueda de la posición empieza cerca de la última conocida, así que una ruta que se cruza a sí misma, o una calle paralela, no hace saltar al vehículo. Si no hay nada cerca, se busca en toda la ruta.
- Con varios vehículos, pasa el `markerId` a `updateVehicle`.
- Combínalo con `markerAnimationMode: MarkerAnimationMode.latestOnly` para seguimiento en vivo.

### Tramos que fluyen: una limitación

Google Maps no puede mover el patrón de una línea punteada, así que `DashFlowAnimator` lo simula recortando el inicio de la línea un poco más en cada frame. `dash` y `gap` se dibujan en píxeles lógicos (lo que usan los patrones de Google Maps), pero el recorte se mide en metros, así que el bucle solo es suave en el nivel de zoom donde un metro equivale a un píxel (alrededor del zoom 17). En otros niveles los tramos pueden dar un salto al reiniciar el ciclo. No se ha comprobado que el patrón quede anclado al primer punto en Android y en iOS.

## Colores por tramo

Dibuja una ruta en varios colores, por ejemplo según el tráfico. Cada segmento es una fracción de la ruta por distancia, y el animator se aplica a toda la ruta como si fuera una sola línea.

```dart
AnimatedPolyline.segmented(
id: const PolylineId('route'),
points: puntosDeLaRuta,
segments: const [
RouteSegment(from: 0.00, to: 0.35, color: Color(0xFF1E9E5A)),
RouteSegment(from: 0.35, to: 0.60, color: Color(0xFFF2A900)),
RouteSegment(from: 0.60, to: 0.80, color: Color(0xFFE53935)),
RouteSegment(from: 0.80, to: 1.00, color: Color(0xFF1E9E5A)),
],
polylineAnimator: const SnackAnimator(), // opcional
)
```

- Cada segmento es una polyline con el ID `<id>#<n>`; el ID en sí no se dibuja. No uses esos IDs para otras polylines.
- Los segmentos consecutivos comparten el punto donde se unen, así que no queda hueco. Una parte de la ruta que ningún segmento cubre no se dibuja.
- Del animator solo se usa la parte de la ruta que deja visible y su opacidad en los fundidos. Los colores vienen de los segmentos.

## Una cámara que sigue

Haz que la cámara siga a un marcador, por ejemplo el vehículo que estás siguiendo:

```dart
mapAnimationController.followCamera(
CameraFollow(
markerId: const MarkerId('driver'),
zoom: 17,
tilt: 45,
bearing: CameraBearing.vehicle, // o CameraBearing.north
onFollowStopped: () => mostrarBotonRecentrar(),
),
);

mapAnimationController.stopFollowingCamera();
```

La cámara se mueve como máximo unas diez veces por segundo, y se envía la última posición cuando el marcador se detiene. **El paquete no recibe por sí solo los gestos sobre el mapa.** Para dejar de seguir cuando el usuario mueve el mapa, pásale el método del controlador al widget:

```dart
GoogleMap(
onCameraMoveStarted: mapAnimationController.onCameraMoveStarted,
// ...
)
```

El mapa también avisa de los movimientos que hace el controlador, así que los que empiezan justo después de una actualización suya de la cámara se ignoran. Por eso se detecta al usuario cuando la cámara lleva un momento sin moverse, por ejemplo cuando el vehículo se detiene. No se ha comprobado en dispositivos cómo lo reporta cada plataforma.

## Batería y accesibilidad

- **Segundo plano.** Por defecto (`pauseInBackground: true`) las animaciones de polylines se detienen cuando la app pasa a segundo plano y continúan desde el mismo punto al volver. Una animación que pausaste con su handle sigue pausada. Los movimientos de marcadores no se pausan, porque tienen que mostrar las posiciones más recientes.
- **Reducir movimiento.** Por defecto (`respectReduceMotion: true`) el controlador sigue el ajuste del sistema. Cuando el usuario pide reducir el movimiento, las polylines se dibujan tal cual, sin animar, y los marcadores y vehículos van a su nueva posición de inmediato. Sobrescribe `PolylineAnimator.reducedMotionFrame` si tu propia animación necesita algo distinto.

## Controla una animación en marcha

Pídele al controlador el handle de una polyline para pausarla, llevarla a un punto o seguir su progreso.

```dart
final animacion = mapAnimationController
.polylineAnimation(const PolylineId('front'));

animacion?.pause();
animacion?.seek(0.5); // salta a la mitad del ciclo
animacion?.resume();

animacion?.progress.listen((p) => print(p)); // de 0.0 a 1.0
animacion?.onComplete = () => mostrarLlegada();
animacion?.onCycle = (ciclo) => print('terminó la pasada $ciclo');
```

- `polylineAnimation` devuelve `null` si ese ID no tiene animación.
- El progreso es la posición dentro de un ciclo, en tiempo: incluye `delayStart` y `delayEnd` y se mide antes de la curva.
- `seek` sobre una animación en marcha la mantiene corriendo desde ahí. En una pausada o terminada se queda quieta hasta `resume`.
- `onComplete` no se llama en una animación que se repite para siempre, porque nunca termina. Para esas usa `onCycle`. Con `reverse`, ir y volver cuentan como una pasada cada uno, igual que en `repeatCount`.
- El handle deja de funcionar cuando se quita la polyline, se reemplaza su animator o se hace `dispose` del controlador.

## Utilidades

```dart
// Decodifica la ruta de una respuesta de Directions y ajusta la cámara.
final ruta = PolylineCodec.decode(respuesta.overviewPolyline);
controller.animateCamera(
CameraUpdate.newLatLngBounds(MapAnimationUtils.boundsOf(ruta), 50),
);

// Y de vuelta a texto, con 5 decimales (por defecto) o 6.
final texto = PolylineCodec.encode(ruta, precision: 6);
```

`PolylineCodec` lee y escribe el [formato de polyline codificada](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). `boundsOf` no maneja rutas que cruzan el meridiano 180.

## Importante: no repitas IDs en `GoogleMap`

El controlador dibuja directamente sobre el mapa usando el `mapId`. Si el widget `GoogleMap` también recibe una polyline o un marcador con el mismo ID en sus `polylines` o `markers`, el widget sobrescribe lo que dibuja el controlador. Dale al controlador sus propios IDs y no los incluyas en los conjuntos del widget.
Expand Down
Loading
Loading