# OpenFlock Survey

OpenFlock Survey is an open-source toolkit for collecting standardized bird observations from community scientists. It supports repeatable point counts, incidental sightings, effort tracking, and exports suitable for ecological analysis.

## Overview

The project helps local birding groups, schools, conservation organizations, and individual observers run consistent surveys. Observations are stored locally by default, so fieldwork can continue without an internet connection.

OpenFlock records:

- Species and number observed
- Detection method, such as visual or heard
- Survey location and timestamp
- Observation duration and distance
- Weather and habitat conditions
- Observer effort and optional notes

> Never disturb birds or enter restricted property to complete a survey. Avoid publishing precise locations for nests or sensitive species.

## Features

- Guided point-count and transect surveys
- Incidental sighting records
- Offline data entry
- Configurable species checklists and survey protocols
- Automatic timestamps and optional GPS coordinates
- Validation for counts, dates, and required effort fields
- CSV and GeoJSON exports
- Sensitive-location coordinate masking
- Duplicate-record detection
- Multi-observer support

## Install

OpenFlock requires Python 3.11 or later.

```bash
git clone https://github.com/openflock/openflock-survey.git
cd openflock-survey

python -m venv .venv
source .venv/bin/activate
pip install -e .
```

On Windows PowerShell, activate the environment with:

```powershell
.venv\Scripts\Activate.ps1
```

Verify the installation:

```bash
openflock --version
```

## Usage

Initialize a survey workspace:

```bash
openflock init spring-count
cd spring-count
```

Start a 10-minute point count:

```bash
openflock survey start --protocol point-count --duration 10m
```

Record observations in another terminal:

```bash
openflock observe "American Robin" --count 3 --method visual
openflock observe "Northern Cardinal" --count 1 --method heard
```

Finish the active survey:

```bash
openflock survey finish
```

Review and validate records:

```bash
openflock records list
openflock validate
```

Export validated observations:

```bash
openflock export observations.csv
openflock export observations.geojson --format geojson
```

For incidental sightings that are not part of a timed survey:

```bash
openflock observe "Red-tailed Hawk" \
  --count 1 \
  --method visual \
  --incidental \
  --lat 43.6532 \
  --lon -79.3832
```

Run `openflock --help` or `openflock <command> --help` for the complete command reference.

## Configuration

Project settings are stored in `openflock.toml`, created by `openflock init`.

```toml
[project]
name = "Spring Neighborhood Bird Count"
timezone = "America/Toronto"
default_protocol = "point-count"

[observer]
id = "observer-001"
name = "Example Observer"

[protocols.point-count]
duration_minutes = 10
radius_meters = 100
require_weather = true

[location]
source = "device"
coordinate_precision = 5

[privacy]
mask_sensitive_species = true
mask_radius_km = 5
omit_observer_name_from_exports = false

[checklist]
region = "CA-ON"
language = "en"

[export]
directory = "exports"
date_format = "%Y-%m-%d"
include_unvalidated = false
```

Command-line flags override configuration values for a single command. Environment variables use the `OPENFLOCK_` prefix and double underscores for nested keys:

```bash
export OPENFLOCK_PROJECT__TIMEZONE="America/Vancouver"
export OPENFLOCK_PRIVACY__MASK_RADIUS_KM="10"
```

Do not commit personal information, access credentials, or unmasked sensitive-species locations. For shared projects, commit an example configuration and keep observer-specific settings in an ignored local file.