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:

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:

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 for the checked release process.

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

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, THIRD_PARTY_NOTICES.md, and 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

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:

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 -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:

.\.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:

.\scripts\webcam.ps1

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

.\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

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.

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.