Documentation for `PyPortal.Job`

Module for Cloud Portal jobs.

Job

Job(
    project_id: str,
    actor_name: str,
    tracking_model: TrackingModel,
    video_file_path: Optional[str] = None,
    calibration_image_file_path: Optional[str] = None,
    video_rotation: Optional[VideoRotation] = NONE,
    tracking_version: Optional[str] = None,
)

A class encapsulating submittable and retriable Cloud Portal Job.

Intended to be initialized via the project, not directly. To submit a job for processing, use the Project.submit_job() method.

Warning

The status, progress, processing_seconds and extended_status properties are not updated in real-time and added only for filtering purposes when the jobs are loaded via project get_job and get_jobs methods.

For the latest status and progress changes use the following methods:

- get_status(), it will also update .status and .extended_status property; returns last status only
- get_progress(), it will also update .progress property; returns last progress in percentage

Warning

The video_name property is available only when the jobs are loaded via get_job and get_jobs methods. Otherwise, video_file_path can be used.

Initialize Job.

Parameters:

Name	Type	Description	Default
`project_id`	`str`	Identifier for the project within the organization.	required
`actor_name`	`str`	Name of the actor.	required
`tracking_model`	`TrackingModel`	The model to be used for video tracking.	required
`video_file_path`	`Optional[str]`	Path to the video file to be processed.	`None`
`calibration_image_file_path`	`Optional[str]`	Optional path to calibration image.	`None`
`video_rotation`	`Optional[VideoRotation]`	Specifies the rotaation. Default is 'NONE'.	`NONE`
`tracking_version`	`Optional[str]`	Optional tracking version. Default is 'None'.	`None`

extended_status `property`

extended_status

Returns job extended status if any.

id `property`

id

Returns job ID if any.

Will be None if the job was not submitted yet.

processing_seconds `property`

processing_seconds

Returns job processing seconds if any.

progress `property`

progress

Returns job progress if any.

Will be None if the job was not submitted yet.

status `property`

status

Returns job status.

Will return JobStatus.NOT_SUBMITTED if the job was not submitted yet.

video_name `property`

video_name

Returns video name if any.

Will be None if the job was not submitted yet.

delete `async`

delete() -> bool

Will delete the job if the job status is either completed, failed, canceled or in queue.

Returns:

Type	Description
`bool`	True if the job deletion was successful. False, otherwise

Raises:

Type	Description
`PortalHTTPException`	If there was an error while communicating with Faceware Portal.

download_analyzer_file `async`

download_analyzer_file(
    absolute_file_name: str,
    progress_listener: Optional[
        Callable[[float], None]
    ] = None,
) -> bool

Will download the Faceware Analyzer.

For more information, visit: Faceware Analyzer

Parameters:

Name	Type	Description	Default
`absolute_file_name`	`str`	The location on the local filesystem where Analyzer file will be downloaded.	required
`progress_listener`	`Optional[Callable[[float], None]]`	A callback to track the download progress.	`None`

progress_listener example

def progress_listener(progress) -> None:
    print(f"Upload progress: {progress}%")

Returns:

Type	Description
`bool`	True if download was successful. False otherwise.

Raises:

Type	Description
`PortalHTTPException`	If there was an error while communicating with Faceware Portal.
`DownloadError`	If there was an error while downloading with Faceware Portal.
`FileNotFoundError`	If the parent directory path to the absolute_file_name does not exists on filesystem.

download_control_data `async`

download_control_data(
    absolute_file_name: str,
    progress_listener: Optional[
        Callable[[float], None]
    ] = None,
) -> bool

Will download the FacewareTech Portal Controls JSON file.

Parameters:

Name	Type	Description	Default
`absolute_file_name`	`str`	The location on the local filesystem where JSON file will be downloaded.	required
`progress_listener`	`Optional[Callable[[float], None]]`	A callback to track the download progress.	`None`

progress_listener example

def progress_listener(progress) -> None:
    print(f"Upload progress: {progress}%")

Returns:

Type	Description
`bool`	True if download was successful. False otherwise.

Raises:

Type	Description
`PortalHTTPException`	If there was an error while communicating with FacewareTech Portal.
`DownloadError`	If there was an error while downloading with FacewareTech Portal.
`FileNotFoundError`	If the parent directory path to the absolute_file_name does not exists on filesystem.

download_retargeting_file `async`

download_retargeting_file(
    absolute_file_name: str,
    progress_listener: Optional[
        Callable[[float], None]
    ] = None,
) -> bool

Will download the Faceware Retargeter.

For more information, visit: Faceware Retargeter

Parameters:

Name	Type	Description	Default
`absolute_file_name`	`str`	The location on the local filesystem where retargeting file will be downloaded.	required
`progress_listener`	`Optional[Callable[[float], None]]`	A callback to track the download progress.	`None`

progress_listener example

def progress_listener(progress) -> None:
    print(f"Upload progress: {progress}%")

Returns:

Type	Description
`bool`	True if download was successful. False otherwise.

Raises:

Type	Description
`PortalHTTPException`	If there was an error while communicating with Faceware Portal.
`DownloadError`	If there was an error while downloading with Faceware Portal.
`FileNotFoundError`	If the parent directory path to the absolute_file_name does not exists on filesystem.

download_validaton_video `async`

download_validaton_video(
    absolute_file_name: str,
    progress_listener: Optional[
        Callable[[float], None]
    ] = None,
) -> bool

Will download the Faceware Portal tracking quality validation video file.

Parameters:

Name	Type	Description	Default
`absolute_file_name`	`str`	The location on the local filesystem where JSON file will be downloaded.	required
`progress_listener`	`Optional[Callable[[float], None]]`	A callback to track the download progress.	`None`

progress_listener example

def progress_listener(progress) -> None:
    print(f"Upload progress: {progress}%")

Returns:

Type	Description
`bool`	True if download was successful. False otherwise.

Raises:

Type	Description
`PortalHTTPException`	If there was an error while communicating with Faceware Portal.
`DownloadError`	If there was an error while downloading with Faceware Portal.
`FileNotFoundError`	If the parent directory path to the absolute_file_name does not exists on filesystem.

get_progress `async`

get_progress() -> Optional[int]

Get current progress.

Raises:

Type	Description
`PortalHTTPException`	If there was an error while communicating with Faceware Portal.

Usage Example

    while True:
        progress = await job.get_progress()
        logging.info(f"Progress: {progress}%")
        await asyncio.sleep(5)  # Wait before checking again

Returns:

Type	Description
`Optional[int]`	A progress for submitted or completed jobs. None otherwise.

get_status `async`

get_status() -> JobStatus

Get current status. Running get_status() will also refresh status and extended_status (if any) properties

Raises:

Type	Description
`PortalHTTPException`	If there was an error while communicating with Faceware Portal.

Usage Example

    while True:
        status = await job.get_status()
        if status in [JobStatus.COMPLETED, JobStatus.FAILED]:
            break
        logging.info("Waiting for job status to change...")
        await asyncio.sleep(5)  # Wait before checking again

Returns:

Type	Description
`JobStatus`	JobStatus.

move `async`

move(target_project_id: str) -> bool

Will move the job to another project if the job status is completed, failed or canceled.

Parameters:

Name	Type	Description	Default
`target_project_id`	`str`	The ID of the target (destination) project	required

Returns:

Type	Description
`bool`	True if the job moved successfully. False, otherwise

Raises:

Type	Description
`PortalHTTPException`	If there was an error while communicating with FacewareTech Portal.

JobStatus

Job status type.

CANCELED `class-attribute` `instance-attribute`

CANCELED = 'CANCELED'

Job was canceled.

COMPLETED `class-attribute` `instance-attribute`

COMPLETED = 'COMPLETED'

Job has finished being processed and results are ready to download.

FAILED `class-attribute` `instance-attribute`

FAILED = 'FAILED'

Job has failed processing.

IN_PROGRESS `class-attribute` `instance-attribute`

IN_PROGRESS = 'IN PROGRESS'

Job is actively being processed.

NOT_FOUND `class-attribute` `instance-attribute`

NOT_FOUND = 'NOT FOUND'

Job was not found.

NOT_SUBMITTED `class-attribute` `instance-attribute`

NOT_SUBMITTED = 'NOT SUBMITTED'

Job was not submitted for processing yet.

QUEUED `class-attribute` `instance-attribute`

QUEUED = 'QUEUED'

Job is waiting to be processed.

UNKNOWN `class-attribute` `instance-attribute`

UNKNOWN = ''

Unknown status. Something went wrong.

TrackingModel

Tracking models.

HEAD_CAM `class-attribute` `instance-attribute`

HEAD_CAM = 'HeadCam'

The HEAD_CAM tracker is designed to be used specifically with color videos from a head mounted camera. To work properly, the video must be in a vertical orientation (more tall than wide) and the face should be occupying the vast majority of the frame like in the example below.

Tip

Due to the stringent requirements for this tracker, if you are getting errors or an inconsistent track with either Headcam tracker, try using the STATIC_CAM instead to improve your chances of getting a good result

HEAD_CAM_GRAYSCALE `class-attribute` `instance-attribute`

HEAD_CAM_GRAYSCALE = 'HeadCamGrey'

This tracker is almost identical to the HEAD_CAM tracker except for being specifically made for greyscale (black and white) videos and should only be used for that type of footage.

Warning

This tracking model is currently in an experimental evaluation phase.

STATIC_CAM `class-attribute` `instance-attribute`

STATIC_CAM = 'StaticCam'

The STATIC_CAM tracker is designed for use with stationary cameras. The actor's face can take up a varying amount of the total frame and can move around. Due to its flexibility as a tracker, it can be used with virtually any facial footage.

VideoRotation

Rotation angle to be applied while processing the video.

This is useful when video that needs processing was captured in non-standard orientation

NONE `class-attribute` `instance-attribute`

NONE = 0

No rotation

ROTATE_180 `class-attribute` `instance-attribute`

ROTATE_180 = 180

180 degree clockwise

ROTATE_270 `class-attribute` `instance-attribute`

ROTATE_270 = 270

270 degree clockwise

ROTATE_90 `class-attribute` `instance-attribute`

ROTATE_90 = 90

90 degree clockwise

Documentation for PyPortal.Job

Job

extended_status property

id property

processing_seconds property

progress property

status property

video_name property

delete async

download_analyzer_file async

download_control_data async

download_retargeting_file async

download_validaton_video async

get_progress async

get_status async

move async

JobStatus

CANCELED class-attribute instance-attribute

COMPLETED class-attribute instance-attribute

FAILED class-attribute instance-attribute

IN_PROGRESS class-attribute instance-attribute

NOT_FOUND class-attribute instance-attribute

NOT_SUBMITTED class-attribute instance-attribute

QUEUED class-attribute instance-attribute

UNKNOWN class-attribute instance-attribute

TrackingModel

HEAD_CAM class-attribute instance-attribute

HEAD_CAM_GRAYSCALE class-attribute instance-attribute

STATIC_CAM class-attribute instance-attribute

VideoRotation

NONE class-attribute instance-attribute

ROTATE_180 class-attribute instance-attribute

ROTATE_270 class-attribute instance-attribute

ROTATE_90 class-attribute instance-attribute

Documentation for `PyPortal.Job`

extended_status `property`

id `property`

processing_seconds `property`

progress `property`

status `property`

video_name `property`

delete `async`

download_analyzer_file `async`

download_control_data `async`

download_retargeting_file `async`

download_validaton_video `async`

get_progress `async`

get_status `async`

move `async`

CANCELED `class-attribute` `instance-attribute`

COMPLETED `class-attribute` `instance-attribute`

FAILED `class-attribute` `instance-attribute`

IN_PROGRESS `class-attribute` `instance-attribute`

NOT_FOUND `class-attribute` `instance-attribute`

NOT_SUBMITTED `class-attribute` `instance-attribute`

QUEUED `class-attribute` `instance-attribute`

UNKNOWN `class-attribute` `instance-attribute`

HEAD_CAM `class-attribute` `instance-attribute`

HEAD_CAM_GRAYSCALE `class-attribute` `instance-attribute`

STATIC_CAM `class-attribute` `instance-attribute`

NONE `class-attribute` `instance-attribute`

ROTATE_180 `class-attribute` `instance-attribute`

ROTATE_270 `class-attribute` `instance-attribute`

ROTATE_90 `class-attribute` `instance-attribute`