Metadata-Version: 2.4
Name: neura-fall-detection
Version: 0.1.0
Summary: Real-time multi-person pose and temporal fall detection
Author: Darrien Rafael Wijaya
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Akihiro2004/NFD
Project-URL: Documentation, https://github.com/Akihiro2004/NFD#readme
Project-URL: Issues, https://github.com/Akihiro2004/NFD/issues
Project-URL: Source, https://github.com/Akihiro2004/NFD
Keywords: fall-detection,computer-vision,pose-estimation,movenet,onnx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: ai-edge-litert~=2.1.6
Requires-Dist: numpy<3,>=1.26.4
Requires-Dist: onnxruntime~=1.24.4
Requires-Dist: opencv-python<5,>=4.11
Provides-Extra: train
Requires-Dist: onnx<2,>=1.20.1; extra == "train"
Requires-Dist: torch<3,>=2.11; extra == "train"
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == "dev"
Requires-Dist: onnx<2,>=1.20.1; extra == "dev"
Requires-Dist: pytest<10,>=9.1; extra == "dev"
Requires-Dist: ruff<1,>=0.15; extra == "dev"
Requires-Dist: torch<3,>=2.11; extra == "dev"
Requires-Dist: twine<7,>=6.2; extra == "dev"
Dynamic: license-file

# Neura Fall Detection (NFD)

Neura Fall Detection is a local, real-time Python library for detecting people,
reading their body pose, and checking whether they may have fallen. It includes
the complete NFD model bundle, so users do not need to download weights or run a
setup script after installation.

## Install and run

NFD requires 64-bit Python 3.11 or newer. Install it from PyPI and start the
camera demo:

```console
python -m pip install neura-fall-detection
nfd webcam
```

Press `Q` or Escape to close the camera window. The first run extracts the two
inference models from the installed bundle into the current user's cache. It
does not download anything.

Useful commands:

```console
nfd --help
nfd info
nfd webcam --camera 1
nfd benchmark --frames 100
```

The PyPI command becomes public after the first release upload. Maintainers can
follow [docs/PUBLISHING.md](docs/PUBLISHING.md) for the checked release process.

The final model is still only one `.nfd` file. In a source checkout it lives at:

```text
src/neura_fall_detection/models/nfd-v0.1.0.nfd
```

This file contains the MoveNet MultiPose model, my NFD temporal fall model, the
settings, file checksums, model card, and license notices. You can copy this one
file to another computer without copying the two neural model files separately.

> NFD v0.1 is still a research project. The fall model currently learns from
> generated pose movements, not from a large real-world fall dataset. It is not
> a medical device and should not be the only way to handle an emergency.

## What I made and what came from another project

I made the NFD temporal classifier, generated training data, tracking and
inference code, fall confirmation logic, bundle format, and NFD model weights.
These parts are released under Apache-2.0 and credited to Darrien Rafael Wijaya.

For human and pose detection, NFD uses Google MoveNet MultiPose Lightning. It is
also released under Apache-2.0. MoveNet is still Google and TensorFlow work, so
their credit and license must stay in this project.

More details are available in [MODEL_CARD.md](MODEL_CARD.md),
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), and
[docs/LICENSE_AUDIT.md](docs/LICENSE_AUDIT.md).

## The three-layer idea

The easiest way to understand NFD is to divide it into three layers. These are
processing layers, not three models that I trained from zero.

### Layer 1: Base human and pose model

The first layer uses Google MoveNet MultiPose Lightning. It reads a camera frame
and returns person boxes plus 17 body keypoints for up to six people.

MoveNet is already pretrained by Google. NFD v0.1 does not train MoveNet again
and does not use YOLO in this layer. I chose MoveNet because one model call can
handle human localization and pose estimation together.

### Layer 2: Learning the movement pattern

NFD turns the Layer 1 output into 60 values for every person and frame. The
values describe keypoint positions, pose confidence, person box shape, and body
anchors. NFD then keeps 32 frames, which represents about four seconds at 8 FPS.

This sequence goes into the NFD Temporal Convolutional Network. This is the part
that I trained. It learns four movement patterns:

- `normal`
- `descending`
- `fallen`
- `recovering`

NFD v0.1 uses a TCN, not a Graph Neural Network or diffusion model. A future
version could represent body joints as graph nodes and bones as graph edges,
then use a Spatio-Temporal GNN. Diffusion could also help generate more movement
variations. Those ideas are possible next steps, but they are not part of the
current released model.

### Layer 3: Activating the final fall event

The last layer decides whether the pattern is strong enough to create an alert.
It checks whether the person was seen upright, moved down quickly, changed body
posture, moved their hips down, stayed down long enough, or started recovering.

This layer is not another trained neural model in v0.1. It is a self-calibrating
state machine. The temporal model gives it learned probabilities, while the
state machine adds safety checks and timing. A fast movement alone is not enough
to trigger a fall. Confirmation takes between 0.6 and 1.5 seconds, and one fall
only creates one new event.

All three layers, their settings, and the required model files are distributed
through one `.nfd` file and one `NFDModel` API.

## Use it in Python

```python
import cv2
from neura_fall_detection import NFDModel

model = NFDModel()
frame = cv2.imread("frame.jpg")
result = model.process(frame)

for person in result.people:
    print(person.track_id, person.state, person.probabilities)
```

`NFDModel()` automatically uses the model included by pip. An application can
instead use `NFDModel("path/to/custom-model.nfd")` when it needs a custom
bundle. Keep the same `NFDModel` object for every frame because it stores each
person's pose history. The target rate is around 8 processed frames per second.
For a saved video, send its video time with
`model.process(frame, timestamp=seconds)`.

## Work on NFD from source

For normal development without retraining the model:

```powershell
git clone https://github.com/Akihiro2004/NFD.git
cd NFD
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
```

On Linux or macOS, activate the environment and use
`python -m pip install -e ".[dev]"` instead.

To recreate the model bundle from its upstream and generated components, use
the full setup script on Windows PowerShell:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1
```

The setup script creates the Python environment, installs compatible dependency
versions, downloads and verifies MoveNet, trains the full NFD fall model, and
builds the final `.nfd` file. The temporary model files are ignored by Git
because the scripts can create them again. The final `.nfd` file stays in Git
and is included in every wheel.

To retrain it manually:

```powershell
.\.venv\Scripts\python.exe .\scripts\train.py
.\.venv\Scripts\python.exe .\scripts\build_bundle.py
```

## Legacy source commands

The installed `nfd` command is preferred. These source-checkout wrappers remain
available for compatibility:

```powershell
.\scripts\webcam.ps1
```

Press `Q` or Escape to close the camera window. To use another camera:

```powershell
.\scripts\webcam.ps1 --camera 1
```

The window shows the body pose, person ID, current state, risk score, and
inference time. When NFD confirms a new fall, it also prints one JSON event in
the terminal.

## Run the tests and benchmark

```powershell
nfd benchmark --frames 100 --output .\artifacts\benchmark.json
.\.venv\Scripts\python.exe -m pytest
```

The benchmark checks speed, not fall accuracy. The synthetic validation score
only shows that the exported model learned the generated movements correctly.
It must not be advertised as real-world accuracy. The results from this version
are written in [docs/VALIDATION.md](docs/VALIDATION.md).

## What is still needed for a real product

Before using NFD in a sellable safety product, I would collect consented videos
from real rooms and different camera positions. The data should include
different clothes, lighting, mobility aids, blocked body parts, floor exercises,
normal activities, and staged falls. The data agreement must allow commercial
model training.

People and locations should be separated between training and testing. A proper
evaluation should report:

- how many real fall events were detected.
- false alerts per camera-hour.
- median and p95 alert delay.
- results for different rooms, camera angles, lighting, and mobility needs.
- speed on every supported device.

URFD cannot be used to train commercial NFD weights under its current public
terms. Separate permission from the dataset owner would be needed.

## License

NFD is released under Apache-2.0.

Copyright 2026 Darrien Rafael Wijaya.

Please keep the `LICENSE`, `NOTICE`, and third-party credit files when sharing
or selling a product that includes NFD.
