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 0.1.0 is published on PyPI. It requires 64-bit Python 3.11 or newer.
Install it and start the camera demo:
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.
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.
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
1import cv2
2from neura_fall_detection import NFDModel
34model = NFDModel()5frame = cv2.imread("frame.jpg")6result = model.process(frame)78for person in result.people:9print(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:
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.
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.
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.
