Trail Eyes App

A hazard-tracking app for Forest Park, Portland.

Development sponsored by Portland State University and NSF award CIF-2046175.

Downloads

Nightly builds are available through CI from the actions tab. App Store/Play Store builds are not available yet.

The latest nightly builds can be found here:

Warning

Nightly builds are experimental and untested. Builds are distributing for testing purposes only, and may not be stable.

About

Trail Eyes is developed in Flutter. For more information, see the online documentation.

How to Build

Required

• Flutter >= 3.0.0
• Xcode (optional; only required for iOS/MacOS builds)

Installation

1. Clone this project:

   git clone https://github.com/trilliumlab/forest-park-reports-app.git

2. Most work happens on the dev branch. To switch to the dev branch:

   git checkout dev

3. Fetch project dependencies:

   flutter pub get

4. Create a .env file in the project root. This step is required, but adding a mapbox api key is optional.

   MAPBOX_KEY=API_KEY_HERE

Running

1. Run code generation:

   dart run build_runner build

Important

Code generation needs to be run whenever files in lib/model and lib/provider are modified. To have code generation automatically run on save, run dart run build_runner watch

2. Now your can run Trail Eyes:

   flutter run

Note

iOS development requires some extra setup. To configure a signing certificate, open ios/Runner.xcworkspace in Xcode. Ensure you're signed into your development Apple ID, and select Runner in the sidebar. Under Signing & Capabilities, select Automatically manage signing, and select your team under the Team dropdown.

Building

• To build an APK for android:

  flutter build --release apk

• To build an IPA for iOS:

  flutter build --release ipa

Note

The export options must be configured in Xcode manually after the first run. Open build/ios/archive/Runner.xcarchive in Xcode and distribute the IPA. This will produce an ExportOptions.plist that can be used to automatically build IPAs with the same settings in the future. To pass the ExportOptions.plist to flutter, append --export-options-plist=path/to/ExportOptions.plist to the previous command.

Project Structure

forest-park-reports-app
├── android # native Android project
├── assets # app assets
│   ├── icon # Trail Eyes icon
│   └── markers # trail start/end marker
├── ios # native iOS project
├── lib # flutter code src directory
│   ├── model # data models - uses freezed and json_serializable for codegen
│   ├── page # holds pages and widgets
│   │   ├── common # widgets reusable across all pages
│   │   ├── home_page # widgets specific to home_page
│   │   │   ├── map_page # widgets specific to map_page
│   │   │   └── panel_page # widgets specific to panel_page
│   │   └── settings_page # widgets specific to settings_page
│   ├── provider # riverpod providers - all state management should be here
│   └── util # utility/extension functions
├── linux # native Linux project
├── macos # native MacOS project
├── web # native web project
└── windows # native Windows projecct

Assets

The assets/icon folder contains the app icon. This was created in Adobe Illustrator and the source files are [icon 3d.ai](assets/icon/icon 3d.ai) for the main icon and icon.ai for a flat version. icon.png is the full rendered icon, and background.png and foreground.png are separated bg/fg layers (used by android adaptive icons).

Custom icon symbols go in the assets/icons directory (svgs only). The icons are loaded in flutter using a font file. To generate the font file and the dart icon class, run:

dart run icon_font_generator:generator

Contributing

Contributions are welcomed! If you have any suggestions, feel free to open a pull request.

1. Fork the project.
2. Create a new branch git checkout -b feature/new-feature-name
3. Commit your changes git commit -m 'Added new feature
4. Push your changes git push
5. Open a pull request.

Not up for a pull request? Feel free to open an issue.

License

Trail Eyes is provided under the MIT license. See LICENSE.md