@codewithvincent/react-native-gps-filter/README.md

Kalman-based adaptive GPS filter for React Native.

# @codewithvincent/react-native-gps-filter

Kalman-based adaptive GPS filter for React Native using Zustand and expo-location.

---

## Features

- Smooth and adaptive GPS filtering with Kalman filter
- Supports both Expo (`expo-location`) and bare React Native (`@react-native-community/geolocation`) environments
- Provides a React hook powered by Zustand for state management
- Also provides a standalone class API for flexible, hook-less usage
- Adaptive thresholds based on user speed (stationary, walking, running, driving)
- Easy integration into any React Native app

---

## Installation

```bash
npm install @codewithvincent/react-native-gps-filter


If you want to use the React hook, also install:

npm install zustand




Usage

1. React Hook API (requires Zustand)

    This is the easiest way to integrate if you use React and Zustand in your app.


    import React, { useEffect } from 'react';
    import * as LocationExpo from 'expo-location';
    import { useLocationStore } from '@codewithvincent/react-native-gps-filter';

    export default function App() {
    const filterAndAddLocation = useLocationStore(state => state.filterAndAddLocation);

    useEffect(() => {
        (async () => {
        const { status } = await LocationExpo.requestForegroundPermissionsAsync();
        if (status !== 'granted') {
            console.error('Location permission denied');
            return;
        }

        const subscription = await LocationExpo.watchPositionAsync(
            { accuracy: LocationExpo.Accuracy.Highest, distanceInterval: 1 },
            (location) => {
            const result = filterAndAddLocation(location);
            if (result.result) {
                console.log('Filtered location:', result.predictedLocation);
            }
            }
        );

        return () => subscription.remove();
        })();
    }, []);

    return null;
    }




2. Class API (no Zustand needed)

    Use this if you want to manage state yourself or avoid Zustand.


    import { LocationFilter } from '@codewithvincent/react-native-gps-filter';

    const filter = new LocationFilter();

    async function onLocationUpdate(location) {
    const result = filter.filterAndAddLocation(location);
    if (result.result) {
        console.log('Filtered Location:', result.predictedLocation);
    }
    }




API
    useLocationStore (Zustand Hook)

        filterAndAddLocation(location: LocationObject, onPredictLocation?: (LocationObject) => void): FilterResult
        Filters a raw location, returns filtering result.

        resetFilters(): void
        Resets internal Kalman filters and state.


    LocationFilter Class

        filterAndAddLocation(location: LocationObject, onPredictLocation?: (LocationObject) => void): FilterResult
        Same as above but in class form for manual control.

        resetFilters(): void
        Resets internal filters and state.


Notes
    This package supports both Expo Managed and Bare React Native projects by auto-detecting environment to use the appropriate location API.

    For best results, ensure location permissions are granted and GPS accuracy is high.


License
MIT © Vincent
```