modelhealth

Initialises the service and validates the API key format.

Arguments:

• api_key: Your Model Health API key, available in the dashboard at modelhealth.io.

Raises:

• AuthenticationError: If the API key is empty or invalid.

Example:

from modelhealth import ModelHealthService

service = ModelHealthService("your_api_key")

# List sessions and subjects
sessions = service.session_list()
subjects = service.subject_list()

Retrieves all sessions for the account associated with the API key.

Use this to list existing sessions before creating a new one, or to resume a previous capture workflow.

To connect a device to a specific session, use the session qrcode URL to download the QR code image data, then display it in your app to be captured by the ModelHealth mobile app.

Returns:

A list of Session objects, or an empty list if none exist.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

import urllib.request

sessions = service.session_list()
print(f"Found {len(sessions)} sessions")

if sessions:
    first = sessions[0]
    with urllib.request.urlopen(first.qrcode) as resp:
        qr_image_data = resp.read()
    # Display qr_image_data in your app so the mobile app can scan it

Retrieve a specific session by ID with all activities populated.

Arguments:

• session_id: The id of the session to retrieve.

Returns:

A Session with activities populated.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the session does not exist.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

session = service.get_session("abc123")
for activity in session.activities:
    print(f"{activity.name or activity.id}")

Creates a session.

A session is the parent container for a movement capture workflow. It links related entities such as activities and subjects and provides the context used by subsequent operations.

Default session settings are applied automatically. Call configure_session() afterwards to override specific settings.

Returns:

A new Session with a unique identifier.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

session = service.create_session()

Applies settings to an existing session.

Call this after create_session() and before calibration to override any default settings. If not called, the session retains the defaults applied during creation.

All parameters are optional — omit any to keep its default.

Arguments:

• session: The session to configure.
• framerate: Camera frame rate. Default: SessionFramerate.fps_120.
• opensim_model: OpenSim model. Default: SessionOpenSimModel.lai_uhlrich_2022_shoulder.
• scaling_setup: Scaling pose. Default: SessionScalingSetup.upright_standing_pose.
• core_engine: Core engine version. Default: SessionCoreEngine.v1_0.
• filter_frequency: Low-pass filter frequency. Default: FilterFrequencyDefault().
• data_sharing: Data-sharing preference. Default: SessionDataSharing.share_processed_data_and_identified_videos.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

session = service.create_session()
service.configure_session(
    session,
    framerate=SessionFramerate.fps_60,
    data_sharing=SessionDataSharing.share_no_data,
)

Retrieves all subjects associated with the API key.

Subjects represent individuals being monitored or assessed. Each subject may contain demographic information, physical measurements, and categorization tags.

Returns:

A list of Subject objects, or an empty list if none exist.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

subjects = service.subject_list()
for subject in subjects:
    print(f"{subject.name}: {subject.height}cm, {subject.weight}kg")

Creates a subject profile.

Height and weight are required for biomechanical analysis. Once created, the subject can be calibrated using calibrate_subject().

Arguments:

• parameters: The subject's profile details including name and anthropometrics.

Returns:

The newly created Subject with its assigned ID.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On validation failure, server error or unexpected response.

Example:

from modelhealth import SubjectParameters

params = SubjectParameters(
    name="John Smith",
    weight=75.0,
    height=180.0,
    birth_year=1990,
)
subject = service.create_subject(params)
print(f"Created subject with ID: {subject.id}")

# Use the subject for calibration
service.calibrate_subject(subject, session, lambda s: print(s))

Retrieves activities for a specific subject with pagination and sorting.

Use this to display a subject's activity history or implement paginated list interfaces.

Arguments:

• subject: The subject whose activities to retrieve.
• start_index: Zero-based index to start from. Use 0 for the first page.
• count: Number of activities to retrieve per request.
• sort: Sort order — currently only "updated_at" (most recently updated first).

Returns:

A list of Activity objects, or an empty list if none exist.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

# First page
page1 = service.activities_for_subject(
    subject, start_index=0, count=20
)

# Next page
page2 = service.activities_for_subject(
    subject, start_index=20, count=20
)

Retrieves an activity by its ID.

Use this to fetch the latest state of an activity, including its videos, results and current processing status.

Arguments:

• activity_id: The unique identifier of the activity.

Returns:

The Activity with its current details.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the activity does not exist.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

activity = service.fetch_activity("abc123")
print(f"Activity: {activity.name or 'Unnamed'}")
print(f"Status: {activity.status}")

Updates an activity.

Only mutable fields (such as name) are applied on the server. Use the returned object rather than the input going forward.

Arguments:

• activity: The Activity to update, with modified properties.

Returns:

The updated Activity as stored on the server.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the activity does not exist.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Deletes an activity.

Permanently removes the activity and all associated videos, results, and metadata.

Arguments:

• activity: The Activity to delete.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the activity does not exist.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

service.delete_activity(activity)

Warning:

This operation is irreversible.

Retrieves all available activity tags.

Use the returned tags to populate a tag picker or validate tag values before assigning them to activities.

Returns:

A list of ActivityTag objects, or an empty list if none are configured.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

tags = service.activity_tags()
for tag in tags:
    print(f"{tag.label}: {tag.value}")

Retrieves all movement activities associated with a session.

Activities represent individual recording trials and contain references to captured videos and results. Use this to review past data or fetch results for completed activities.

Arguments:

• session: The session whose activities to retrieve.

Returns:

A list of Activity objects, or an empty list if none exist.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

activities = service.activity_list(session)
for activity in activities:
    print(f"{activity.name or activity.id}")
    print(f"  Videos: {len(activity.videos)}")
    print(f"  Results: {len(activity.results)}")

Downloads video data for a specific activity.

Fetches all videos associated with the activity that match the specified version. Videos with invalid URLs or failed downloads are silently excluded from the result.

Arguments:

• activity: The Activity whose videos to download.
• version: VideoVersion.raw for original per-camera recordings, or VideoVersion.synced for temporally-synchronised output.

Returns:

A list of raw video bytes (one per camera). Write each element to a .mp4 file for playback. May be empty if no videos are available or all downloads fail.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

videos = service.videos_for_activity(activity, VideoVersion.synced)
for i, video in enumerate(videos):
    with open(f"video_{i}.mp4", "wb") as f:
        f.write(video)

Downloads motion data from a processed activity.

Use this after an activity reaches ActivityStatus.ready to retrieve biomechanical result files such as kinematics, marker data, or an OpenSim model. Failed downloads are silently excluded from results.

Arguments:

• activity: The Activity whose results to download. Must have completed processing.
• data_types: Motion data types to fetch. Valid values: "animation", "kinematics_mot", "kinematics_csv", "markers_trc", "markers_csv", "model".

Returns:

A list of MotionData objects, one per successfully downloaded type. May be empty if no results are available or all downloads fail.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

results = service.motion_data_for_activity(
    activity, [MotionDataType.kinematics_mot, MotionDataType.animation]
)
for r in results:
    if r.type == "kinematics_mot":
        with open("kinematics.mot", "wb") as f:
            f.write(r.data)  # MOT format
    elif r.type == "animation":
        import json
        transforms = json.loads(r.data)  # JSON format
    elif r.type == "markers_trc":
        with open("markers.trc", "wb") as f:
            f.write(r.data)  # TRC format
    elif r.type == "model":
        with open("model.osim", "wb") as f:
            f.write(r.data)  # OSim format

Downloads result data for an activity with a completed analysis.

Call this after analysis_status() returns AnalysisStatus.completed to retrieve metrics, a report, or raw data. Failed downloads are silently excluded from results.

Arguments:

• activity: The Activity whose analysis results to download. Must have a completed analysis.
• data_types: Analysis result types to fetch. Valid values: "metrics" (JSON), "report" (PDF), "data" (ZIP).

Returns:

A list of AnalysisData objects, one per successfully downloaded type. May be empty if no results are available or all downloads fail.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

import json

results = service.analysis_data_for_activity(
    activity, [AnalysisDataType.metrics, AnalysisDataType.report, AnalysisDataType.data]
)
for r in results:
    if r.type == "metrics":
        metrics = json.loads(r.data)
    elif r.type == "report":
        with open("report.pdf", "wb") as f:
            f.write(r.data)
    elif r.type == "data":
        with open("data.zip", "wb") as f:
            f.write(r.data)

Retrieves the current processing status of an activity.

Poll this method after recording stops to track upload and processing progress.

Returns ActivityStatusUploading when videos are uploading, ActivityStatusAnalyzing (with the analysis task) when automatic analysis is running, or an ActivityStatus enum value otherwise.

Arguments:

• activity: The Activity to check status for.

Returns:

The current status as ActivityStatusUploading, ActivityStatusAnalyzing, or ActivityStatus.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

status = service.activity_status(activity)
if isinstance(status, ActivityStatusUploading):
    print(f"Uploading: {status.uploaded}/{status.total}")
elif status == ActivityStatus.processing:
    print("Still processing...")
elif isinstance(status, ActivityStatusAnalyzing):
    analysis_status = service.analysis_status(status.task)
elif status == ActivityStatus.ready:
    print("Activity ready for analysis")
elif status == ActivityStatus.failed:
    print("Processing failed")

Starts an analysis task for an activity that is ready for analysis.

Call this after activity_status() returns ActivityStatus.ready. Use the returned Analysis with analysis_status() to poll progress.

Arguments:

• activity_type: The analysis algorithm to run. Use a ActivityType member.
• activity: The Activity to analyze.
• session: The Session containing the activity.

Returns:

An Analysis for tracking analysis progress.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If the activity is not ready or the request fails.

Example:

task = service.start_analysis(
    ActivityType.counter_movement_jump, activity, session
)
status = service.analysis_status(task)

Retrieves the current status of an analysis task.

Poll this method after start_analysis() to monitor progress. When status reaches AnalysisStatus.completed, download results with analysis_data_for_activity().

Arguments:

• task: The Analysis task returned by start_analysis().

Returns:

The current AnalysisStatus.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

import time

status = service.analysis_status(task)
while status == AnalysisStatus.processing:
    time.sleep(10)
    status = service.analysis_status(task)

if status == AnalysisStatus.completed:
    results = service.analysis_data_for_activity(
        activity, [AnalysisDataType.metrics, AnalysisDataType.report]
    )
elif status == AnalysisStatus.failed:
    print("Analysis failed")

Creates an activity and starts recording a dynamic movement trial.

Must be called after both camera and subject calibration are complete. Call stop_recording() when the subject has finished the movement.

Arguments:

• name: A descriptive name for this activity (e.g. "cmj", "squat").
• session: The session this activity is associated with.
• config: Optional recording configuration.

Returns:

The newly created Activity.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If recording cannot start (e.g. missing calibration).

Example:

activity = service.start_recording("cmj", session, ActivityConfig(ActivityType.counter_movement_jump))
# Subject performs movement...
service.stop_recording(session)

Stops the active recording for a movement trial.

Call this after the subject has completed the movement. Once stopped, the recorded videos begin uploading and can be tracked with activity_status().

Arguments:

• session: The session context to stop recording in.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If there is no active recording or the request fails.

Example:

service.stop_recording(session)

Calibrates cameras using a checkerboard pattern.

Determines each camera's position and orientation in 3D space (extrinsics), enabling reconstruction of real-world movement from multiple 2D video feeds. Required once per session setup — recalibrate only if cameras are moved.

Note:

rows and columns refer to internal corners, not squares. A 5×6 board has 4 internal corner rows and 5 internal corner columns.

This method blocks until calibration completes. The status_callback is called synchronously on each status update during the operation.

Arguments:

• session: The session context in which calibration is performed.
• checkerboard: The checkerboard dimensions and placement.
• status_callback: Callable receiving a CalibrationStatus, CalibrationStatusUploading or CalibrationStatusProcessing on each update.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If calibration fails (e.g. pattern not detected).

Example:

from modelhealth import CheckerboardDetails, CheckerboardPlacement

details = CheckerboardDetails(
    rows=4,       # Internal corners, not squares (for 5×6 board)
    columns=5,    # Internal corners, not squares (for 5×6 board)
    square_size=35,  # Measured in millimeters
    placement=CheckerboardPlacement.perpendicular,
)
service.calibrate_camera(session, details, lambda s: print(s))

Calibrates a subject by recording a neutral standing pose.

Scales the 3D biomechanical model to the subject's body size. Must be run after camera calibration and requires the subject profile to include height and weight.

Important:

The subject must stand upright, feet pointing forward, completely still and fully visible to all cameras for the duration of the recording.

This method blocks until calibration completes. The status_callback is called synchronously on each status update during the operation.

Arguments:

• subject: The subject to calibrate.
• session: The session context in which calibration is performed.
• status_callback: Callable receiving a CalibrationStatus, CalibrationStatusUploading or CalibrationStatusProcessing on each update.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If calibration fails.

Example:

service.calibrate_subject(subject, session, lambda s: print(s))

Starts preparing a session archive for download.

Kicks off a server-side task that packages the session data into a ZIP file. Poll archive_status() until status reaches ArchiveStatus.ready, then call archive_data() to download the ZIP file.

Arguments:

• session: The Session to archive.
• with_videos: If True, include raw video files in the archive. Defaults to False.

Returns:

An Archive for tracking preparation progress.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

import time

archive = service.prepare_archive(session)
status = service.archive_status(archive)
while status == ArchiveStatus.processing:
    time.sleep(5)
    status = service.archive_status(archive)

if status == ArchiveStatus.ready:
    data = service.archive_data(archive)
    with open("session.zip", "wb") as f:
        f.write(data)

Retrieves the current preparation status of an archive task.

Poll this method after prepare_archive() to monitor progress. When status reaches ArchiveStatus.ready, download the archive with archive_data().

Arguments:

• archive: The Archive task returned by prepare_archive().

Returns:

The current ArchiveStatus.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error or unexpected response.

Example:

status = service.archive_status(archive)

if status == ArchiveStatus.processing:
    print("Archive being prepared...")
elif status == ArchiveStatus.ready:
    print("Archive ready to download")
elif status == ArchiveStatus.failed:
    print("Archive preparation failed")

Imports a set of activities into Model Health.

Performs the full import workflow: session creation, configuration, subject association, activity creation, video download and upload, processing trigger and polling until complete for each activity.

Arguments:

• activities_json: Raw JSON string of a JSON array of activity objects.
• subject: Subject to associate with the session.
• session_config: Session settings. None uses defaults.
• session_meta_json: Optional JSON string of the source session's meta field. When provided, the new session is patched with this metadata before settings are applied, preserving source data (e.g. sessionWithCalibration) needed for processing.
• status_callback: Optional callable invoked at each step with a status value. Receives one of: "creating_session", ImportStatusCreatedSession, ImportStatusUploading, or "processing".

Returns:

The Session containing all imported activities.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On server error, invalid JSON or processing failure.

Example:

import json

activities_json = json.dumps([{...}, {...}])  # list of activity dicts

def on_status(status):
    if isinstance(status, ImportStatusUploading):
        print(f"[{status.trial}] Uploading {status.uploaded}/{status.total}")
    else:
        print(status)

session = service.import_session(
    activities_json,
    subject,
    status_callback=on_status,
)

Downloads the prepared session archive as a ZIP file.

Call this after archive_status() returns ArchiveStatus.ready.

Arguments:

• archive: The Archive task returned by prepare_archive().

Returns:

Raw ZIP bytes. Write directly to a .zip file.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If the archive is not ready or the download fails.

Example:

data = service.archive_data(archive)
with open("session.zip", "wb") as f:
    f.write(data)

Unique identifier.

ID of the account that owns this session.

Activities associated with this session.

Total number of activities in this session.

ID of the subject associated with this session, or None if not set.

Display name of the session.

URL of the QR code image for pairing cameras, or None if not available.

Whether the session is publicly visible.

Internal session name. Prefer name for display purposes.

Raw processing status string. Use ModelHealthService.activity_status() for the typed value.

ID of the parent session.

Recorded video files associated with this activity.

Processed result files associated with this activity.

Display name, or None if not set.

Unique identifier.

Unique identifier.

Result tag identifying the content type (e.g. "ik_results", "marker_data").

URL of the result file, or None if not yet available.

ID of the parent activity.

URL of the video thumbnail, or None if not yet available.

Unique identifier.

URL of the full video, or None if not yet available.

ID of the parent activity.

Sex assigned at birth.

Weight in kilograms, or None if not set.

Age in years, or None if not set.

Year of birth, or None if not set.

Display name.

Freeform text describing relevant characteristics or medical conditions.

Unique identifier.

Gender identity.

Height in centimetres, or None if not set.

Year of birth, or None if not provided.

Height in centimetres.

Sex assigned at birth.

Display name.

Weight in kilograms.

Gender identity.

Freeform text describing relevant characteristics or medical conditions.

Machine-readable tag identifier.

Human-readable display label.

The raw file bytes. Parse according to the format implied by type.

The type of result data and its implicit file format.

The raw file bytes. Parse according to the format implied by type.

The type of analysis result and its implicit file format.

Unique task identifier.

Visualisation transforms. JSON format.

Inverse-kinematics results. MOT format.

Inverse-kinematics results. CSV format.

Marker trajectories. TRC format.

Marker trajectories. CSV format.

OpenSim musculoskeletal model. OSim format.

Computed biomechanical metrics. JSON format.

Analysis report. PDF format.

Raw analysis data. ZIP format.

Original per-camera recordings.

Temporally-synchronised output.

Most recently updated first.

Checkerboard upright, plane perpendicular to the ground.

Checkerboard flat on the floor, plane parallel to the ground.

Videos have been uploaded and are being processed.

Processing is complete. The activity is ready for analysis.

Processing failed.

Number of videos successfully uploaded so far.

Total number of videos expected from all cameras.

The analysis task. Pass to ModelHealthService.analysis_status().

Analysis is in progress.

Analysis completed successfully.

Analysis failed.

Archive is being prepared.

Archive is ready to download.

Archive preparation failed.

All connected cameras are actively recording.

Calibration completed successfully.

Number of videos successfully uploaded so far.

Total number of videos expected from all cameras.

Processing completion percentage (0–100), or None if unavailable.

Number of internal corner columns.

Checkerboard orientation: "perpendicular" or "parallel".

Number of internal corner rows.

Size of each square in millimetres.

Camera frame rate. Default: fps_120.

OpenSim musculoskeletal model. Default: lai_uhlrich_2022_shoulder.

Scaling pose. Default: upright_standing_pose.

Core processing engine version. Default: v1_0.

Low-pass filter frequency. Default: server-chosen.

Data-sharing preference. Default: share_processed_data_and_identified_videos.

60 frames per second. Suggested maximum recording duration: 60 s.

120 frames per second (default). Suggested maximum recording duration: 30 s.

240 frames per second. Suggested maximum recording duration: 15 s.

Full-body model with 33 degrees of freedom plus a 6-DoF shoulder complex with a scapulothoracic body and a glenohumeral joint using the ISB-recommended Y-X-Y rotation sequence. Default.

Same full-body model as lai_uhlrich_2022_shoulder without the ISB shoulder complex.

Subject stands straight with feet pointing forward and no bending or rotation at the hips, knees, or ankles. Default.

No posture assumptions. Use when the subject cannot adopt the upright standing pose. Requires all body segments to be visible by at least two cameras.

Version 0.2.

Version 0.3.

Version 1.0 (default).

Share processed data and identified videos (default).

Share processed data and de-identified videos (faces blurred).

Share processed data only. No videos are shared.

Share no data for internal development.

Frequency in Hz.

ID of the newly created session.

Name of the trial whose video is being uploaded.

Number of videos successfully uploaded so far.

Total number of videos to upload.