Class ModelHealthService

Model Health SDK Client for biomechanical analysis.

Main entry point for interacting with the Model Health SDK. Provides authentication, session management, data download, and analysis capabilities.

Example: Create with API key

const client = new ModelHealthService({
  apiKey: "your-api-key-here"
});
await client.init();

// SDK is ready to use
const sessions = await client.sessionList();

Example: With custom configuration

const client = new ModelHealthService({
  apiKey: "your-api-key"
});
await client.init();

Constructors

constructor

new ModelHealthService(config: ModelHealthConfig): ModelHealthService
Create a new Model Health client.
Parameters
- config: ModelHealthConfig
  Configuration options including API key
Returns ModelHealthService
Throws
If API key is not provided
Example: Default configuration
```
const client = new ModelHealthService({
  apiKey: "your-api-key-here"
});
```
Example: Custom configuration
```
const client = new ModelHealthService({
  apiKey: "your-api-key",
  autoInit: false
});
```

Methods

activitiesForSubject

activitiesForSubject(
    subjectId: number,
    startIndex: number,
    count: number,
    sort: "updated_at",
): Promise<Activity[]>
Retrieves activities for a specific subject with pagination and sorting.

Use this to display a subject's activity history or implement paginated list interfaces.
Parameters
- subjectId: number
  The ID of the subject whose activities to retrieve.
- startIndex: number
  Zero-based index to start from. Use 0 for the first page.
- count: number
  Number of activities to retrieve per request.
- sort: "updated_at"
  Sort order for the results (for example, "updated_at" for most recent first).
Returns Promise<Activity[]>
An array of Activity objects, or an empty array if none exist.
Throws
If the request fails due to network or authentication issues.
Example
```
// First page
const page1 = await client.activitiesForSubject(
  subject.id,
  0,
  20,
  "updated_at"
);

// Next page
const page2 = await client.activitiesForSubject(
  subject.id,
  20,
  20,
  "updated_at"
);
```

activityList

activityList(sessionId: string): Promise<Activity[]>
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.
Parameters
- sessionId: string
  The session ID to retrieve activities for.
Returns Promise<Activity[]>
An array of Activity objects, or an empty array if none exist.
Throws
If the request fails due to network or authentication issues.
Example
```
const activities = await client.activityList(session.id);

for (const activity of activities) {
  console.log(`Activity: ${activity.name ?? activity.id}`);
  console.log(`Videos: ${activity.videos.length}`);
  console.log(`Results: ${activity.results.length}`);
}
```

activityStatus

activityStatus(activity: Activity): Promise<ActivityStatus>

Retrieves the current processing status of an activity.

Poll this method after stopRecording to track upload and processing progress. Once the status reaches ready, pass the activity to startAnalysis.

Parameters

activity: Activity
The activity to check status for.

Returns Promise<ActivityStatus>

The current ActivityStatus.

Throws

If the request fails.

Example

const status = await client.activityStatus(activity);

switch (status.type) {
  case "ready":
    console.log("Activity ready for analysis");
    break;
  case "processing":
    console.log("Still processing...");
    break;
  case "uploading":
    console.log(`Uploaded ${status.uploaded}/${status.total} videos`);
    break;
  case "failed":
    console.log("Processing failed");
    break;
}

activityTags

activityTags(): Promise<ActivityTag[]>
Retrieves all available activity tags.

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

Returns Promise<ActivityTag[]>
An array of ActivityTag objects, or an empty array if none are configured.
Throws
If the request fails due to network or authentication issues.
Example
```
const tags = await client.activityTags();
for (const tag of tags) {
  console.log(`${tag.label}: ${tag.value}`);
}
```

analysisDataForActivity

analysisDataForActivity(
activity: Activity,
dataTypes: AnalysisDataType[],
): Promise<AnalysisData[]>
Downloads result data for an activity with a completed analysis.

Use this after analysisStatus returns completed to retrieve metrics, a report, or raw data. Downloads run concurrently and failed downloads are silently excluded from results.
Parameters
- activity: Activity
  The activity to download analysis results from. Must have a completed analysis.
- dataTypes: AnalysisDataType[]
  The analysis result data types to download (for example, "metrics", "report", "data").
Returns Promise<AnalysisData[]>
An array of AnalysisData, one entry per successfully downloaded type. May be empty if no results are available or all downloads fail.
Example
```
const results = await client.analysisDataForActivity(
  activity,
  ["metrics", "report"]
);

for (const result of results) {
  switch (result.type) {
    case "metrics":
      const json = JSON.parse(new TextDecoder().decode(result.data));
      break;
    case "report":
      // Use result.data directly as a PDF
      break;
    case "data":
      // Use result.data directly as a ZIP file
      break;
  }
}
```

analysisStatus

analysisStatus(task: Analysis): Promise<AnalysisStatus>
Retrieves the current status of an analysis task.

Poll this method after startAnalysis to monitor progress. When status reaches completed, download results with analysisDataForActivity.
Parameters
- task: Analysis
  The task returned from startAnalysis.
Returns Promise<AnalysisStatus>
The current AnalysisStatus.
Throws
If the request fails.
Example
```
const status = await client.analysisStatus(task);

switch (status.type) {
  case "processing":
    console.log("Analysis running...");
    break;
  case "completed":
    console.log("Analysis complete");
    break;
  case "failed":
    console.log("Analysis failed");
    break;
}
```

archiveData

archiveData(archive: Archive): Promise<Uint8Array<ArrayBufferLike>>
Downloads the prepared archive as raw ZIP data.

Call this after archiveStatus returns ready. The download URL is managed internally and cached for the lifetime of the WASM instance.
Parameters
- archive: Archive
  The archive returned from prepareArchive.
Returns Promise<Uint8Array<ArrayBufferLike>>
The raw ZIP file bytes as a Uint8Array.
Throws
If the archive is not yet ready or the download fails.
Example
```
const zipData = await client.archiveData(archive);
// Write zipData to a file or process it in memory
```

archiveStatus

archiveStatus(archive: Archive): Promise<ArchiveStatus>
Retrieves the current status of an archive preparation task.

Poll this method after prepareArchive until the status is ready, then download the archive with archiveData.
Parameters
- archive: Archive
  The archive returned from prepareArchive.
Returns Promise<ArchiveStatus>
The current ArchiveStatus.
Throws
If the request fails.
Example
```
const status = await client.archiveStatus(archive);

switch (status.type) {
  case "processing":
    console.log("Archive being prepared...");
    break;
  case "ready":
    console.log("Archive ready to download");
    break;
  case "failed":
    console.log("Archive preparation failed");
    break;
}
```

calibrateCamera

calibrateCamera(
    session: Session,
    checkerboardDetails: CheckerboardDetails,
    statusCallback: (status: CalibrationStatus) => void,
): Promise<void>
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.
Parameters
- session: Session
  The session context in which calibration is performed.
- checkerboardDetails: CheckerboardDetails
  The checkerboard dimensions and placement used for calibration.
- statusCallback: (status: CalibrationStatus) => void
  Callback called with progress updates during calibration.
Returns Promise<void>
Throws
If calibration fails (for example, checkerboard pattern not detected).
Example
```
const session = await client.createSession();

const details: CheckerboardDetails = {
  rows: 4,           // Internal corners, not squares (for 5×6 board)
  columns: 5,        // Internal corners, not squares (for 5×6 board)
  squareSize: 35,    // Measured in millimeters
  placement: "perpendicular"
};

await client.calibrateCamera(session, details, (status) => {
  console.log(status);
});
```

calibrateSubject

calibrateSubject(
    subject: Subject,
    session: Session,
    statusCallback: (status: CalibrationStatus) => void,
): Promise<void>
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.
Parameters
- subject: Subject
  The subject to calibrate.
- session: Session
  The session context in which calibration is performed.
- statusCallback: (status: CalibrationStatus) => void
  Callback called with calibration status updates.
Returns Promise<void>
Throws
If pose capture fails (for example, subject not detected or insufficient visibility).
Example
```
await client.calibrateSubject(subject, session, (status) => {
  console.log(status);
});
```

configureSession

configureSession(session: Session, config?: SessionConfig): Promise<void>
Applies settings to an existing session.

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

All fields in config are optional — omit any field to keep its default.
Parameters
- session: Session
  The session to configure.
- config: SessionConfig = {}
  The settings to apply. Pass {} to keep all defaults.
Returns Promise<void>
Throws
On network failure or authentication error.
Example
```
const session = await client.createSession();

// Override frame rate and data sharing only
await client.configureSession(session, {
  framerate: 60,
  dataSharing: "Share no data"
});
```

createSession

createSession(): Promise<Session>
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.

Returns Promise<Session>
A new Session with a unique identifier.
Throws
If session creation fails.
Example
```
const session = await client.createSession();
```

createSubject

createSubject(parameters: SubjectParameters): Promise<Subject>
Creates a subject profile.

Height and weight are required for biomechanical analysis. Once created, the subject can be calibrated using calibrateSubject.
Parameters
- parameters: SubjectParameters
  The subject profile details including name and anthropometrics.
Returns Promise<Subject>
The newly created Subject with its assigned ID.
Throws
If creation fails (for example, validation error or duplicate name).
Example
```
const params: SubjectParameters = {
  name: "John Smith",
  weight: 75.0,        // kilograms
  height: 180.0,       // centimeters
  birthYear: 1990,
};

const subject = await client.createSubject(params);
console.log(`Created subject with ID: ${subject.id}`);

// Use the subject for calibration
await client.calibrateSubject(subject, session, (status) => {
  console.log(status);
});
```

deleteActivity

deleteActivity(activity: Activity): Promise<void>
Deletes an activity.

Permanently removes the activity and all associated videos, results and metadata.
Parameters
- activity: Activity
  The activity to delete.
Returns Promise<void>
Throws
If the deletion fails or the request fails.
Example
```
const activity = await client.fetchActivity("abc123");
await client.deleteActivity(activity);
```
Warning: This operation is irreversible.

fetchActivity

fetchActivity(activityId: string): Promise<Activity>
Retrieves an activity by its ID.

Use this to fetch the latest state of an activity, including its videos, results, and current processing status.
Parameters
- activityId: string
  The unique identifier of the activity.
Returns Promise<Activity>
The Activity with its current details.
Throws
If the activity doesn't exist or the request fails.
Example
```
const activity = await client.fetchActivity("abc123");
console.log(`Activity: ${activity.name ?? "Unnamed"}`);
console.log(`Status: ${activity.status}`);
```

importSession

importSession(
    activitiesJson: string,
    subject: Subject,
    config?: SessionConfig,
    statusCallback?: (status: ImportStatus) => void,
): Promise<Session>
Imports a set of trials into a new session.

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

Progress is reported via statusCallback with ImportStatus values.
Parameters
- activitiesJson: string
  A JSON array of trial objects to import.
- subject: Subject
  The subject to associate with the session.
- config: SessionConfig = {}
  Session configuration. Pass {} for defaults.
- statusCallback: (status: ImportStatus) => void = ...
  Callback called with progress updates. Defaults to no-op.
Returns Promise<Session>
The Session containing all imported trials.
Throws
If any step of the import fails.
Example
```
const session = await client.importSession(
  activitiesJson,
  subject,
  null,
  { framerate: 60 },
  (status) => {
    switch (status.type) {
      case "creating_session":
        console.log("Creating session...");
        break;
      case "uploading_video":
        console.log(`[${status.trial}] ${status.uploaded}/${status.total}`);
        break;
      case "processing":
        console.log("Processing...");
        break;
    }
  }
);
```

init

init(): Promise<void>
Initialize the WASM module and client.

Must be called before using any other methods if autoInit: false was specified in the configuration. Safe to call multiple times.

Returns Promise<void>
Throws
If WASM initialization fails
Example
```
const client = new ModelHealthService({
  apiKey: "your-key",
  autoInit: false
});
await client.init();
```

motionDataForActivity

motionDataForActivity(
activity: Activity,
dataTypes: MotionDataType[],
): Promise<MotionData[]>
Downloads motion data from a processed activity.

Use this after an activity reaches ready status to retrieve biomechanical result files such as kinematics, marker data, or an OpenSim model. Downloads run concurrently and failed downloads are silently excluded from results.
Parameters
- activity: Activity
  The activity to download data from. Must have completed processing.
- dataTypes: MotionDataType[]
  The motion data types to download (for example, "kinematics_mot", "markers", "animation").
Returns Promise<MotionData[]>
An array of MotionData, one entry per successfully downloaded type. May be empty if no results are available or all downloads fail.
Example
```
// Download kinematics in MOT format
const results = await client.motionDataForActivity(activity, ["kinematics_mot"]);

for (const result of results) {
  switch (result.type) {
    case "kinematics_mot":
      // Use result.data directly as a .mot file
      break;
  }
}
```

prepareArchive

prepareArchive(session: Session, withVideos?: boolean): Promise<Archive>
Begins preparing a session archive.

Kicks off a server-side task that packages the session data into a ZIP file. Poll archiveStatus until the status is ready, then download the archive with archiveData.
Parameters
- session: Session
  The session to archive.
- withVideos: boolean = false
  Whether to include raw videos in the archive. Defaults to false.
Returns Promise<Archive>
An Archive for tracking archive preparation progress.
Throws
If the request fails.
Example
```
const archive = await client.prepareArchive(session);

let status: ArchiveStatus;
do {
  status = await client.archiveStatus(archive);
} while (status.type === "processing");

const zipData = await client.archiveData(archive);
```

sessionList

sessionList(): Promise<Session[]>
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 Promise<Session[]>
An array of Session objects, or an empty array if none exist.
Throws
If the request fails due to network or authentication issues.
Example
```
const sessions = await client.sessionList();
console.log(`Found ${sessions.length} sessions`);

const firstSession = sessions[0];
if (firstSession?.qrcode) {
  const response = await fetch(firstSession.qrcode);
  const qrCodeImageData = new Uint8Array(await response.arrayBuffer());
  // Display qrCodeImageData in your app so the mobile app can scan it
}
```

startAnalysis

startAnalysis(
    activityType: ActivityType,
    activity: Activity,
    session: Session,
): Promise<Analysis>
Starts an analysis task for an activity that is ready for analysis.

Call this after activityStatus returns ready. Use the returned Analysis with analysisStatus to poll progress.
Parameters
- activityType: ActivityType
  The type of analysis to run (for example, "gait", "counter_movement_jump").
- activity: Activity
  The activity to analyze.
- session: Session
  The session context containing the activity.
Returns Promise<Analysis>
An Analysis for tracking analysis progress.
Throws
If the activity is not ready or the request fails.
Example
```
const task = await client.startAnalysis("counter_movement_jump", activity, session);
const status = await client.analysisStatus(task);
```

startRecording

startRecording(
    activityName: string,
    session: Session,
    config?: ActivityConfig,
): Promise<Activity>
Creates an activity and starts recording a dynamic movement trial.

Must be called after both camera and subject calibration are complete. Call stopRecording when the subject has finished the movement.
Parameters
- activityName: string
  A descriptive name for this activity (e.g., "cmj", "squat").
- session: Session
  The session this activity is associated with.
- Optionalconfig: ActivityConfig
  Optional recording configuration.
Returns Promise<Activity>
The newly created Activity.
Throws
If recording cannot start (e.g., missing calibration).
Example
```
const activity = await client.startRecording("cmj", session, { activityType: ActivityType.CounterMovementJump });
// Subject performs movement...
await client.stopRecording(session);
```

stopRecording

stopRecording(session: Session): Promise<void>
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 activityStatus.
Parameters
- session: Session
  The session context to stop recording in.
Returns Promise<void>
Throws
If there is no active recording or the request fails.
Example
```
await client.stopRecording(session);
```

subjectList

subjectList(): Promise<Subject[]>
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 Promise<Subject[]>
An array of Subject objects, or an empty array if none exist.
Throws
If the request fails due to network or authentication issues.
Example
```
const subjects = await client.subjectList();
for (const subject of subjects) {
  console.log(`${subject.name}: ${subject.height ?? 0}cm, ${subject.weight ?? 0}kg`);
}
```

updateActivity

updateActivity(activity: Activity): Promise<Activity>
Updates an activity.

Only mutable fields (such as name) are applied on the server. The server-side state is returned, so use the result rather than the input going forward.
Parameters
- activity: Activity
  The activity to update, with modified properties.
Returns Promise<Activity>
The updated Activity as stored on the server.
Throws
If the update fails or the request fails.
Example
```
let activity = await client.fetchActivity("abc123");
activity.name = "CMJ Baseline Test";
const updated = await client.updateActivity(activity);
console.log(`Updated: ${updated.name ?? "Unnamed"}`);
```

videosForActivity

videosForActivity(
activity: Activity,
version?: VideoVersion,
): Promise<Uint8Array<ArrayBufferLike>[]>
Downloads video data for a specific activity.

Fetches all videos associated with the activity that match the specified version. Downloads run concurrently. Videos with invalid URLs or failed downloads are silently excluded from the result.
Parameters
- activity: Activity
  The activity whose videos should be downloaded.
- version: VideoVersion = "synced"
  The version of videos to download (for example, "raw" or "synced").
Returns Promise<Uint8Array<ArrayBufferLike>[]>
An array of Uint8Array objects. May be empty if no videos are available or all downloads fail.
Example
```
const activity = // ... fetched activity
const videoData = await client.videosForActivity(activity, "raw");

for (const data of videoData) {
  // Process video data
}
```
Downloads run concurrently. Individual download failures do not affect other requests.

Class ModelHealthService

Example: Create with API key

Example: With custom configuration

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns ModelHealthService

Throws

Example: Default configuration

Example: Custom configuration

Methods

activitiesForSubject

Parameters

Returns Promise<Activity[]>

Throws

Example

activityList

Parameters

Returns Promise<Activity[]>

Throws

Example

activityStatus

Parameters

Returns Promise<ActivityStatus>

Throws

Example

activityTags

Returns Promise<ActivityTag[]>

Throws

Example

analysisDataForActivity

Parameters

Returns Promise<AnalysisData[]>

Example

analysisStatus

Parameters

Returns Promise<AnalysisStatus>

Throws

Example

archiveData

Parameters

Returns Promise<Uint8Array<ArrayBufferLike>>

Throws

Example

archiveStatus

Parameters

Returns Promise<ArchiveStatus>

Throws

Example

calibrateCamera

Parameters

Returns Promise<void>

Throws

Example

calibrateSubject

Parameters

Returns Promise<void>

Throws

Example

configureSession

Parameters

Returns Promise<void>

Throws

Example

createSession

Returns Promise<Session>

Throws

Example

createSubject

Parameters

Returns Promise<Subject>

Throws

Example

deleteActivity

Parameters

Returns Promise<void>

Throws