pyroclient.client#
The client subpackage contains the core definition of the API client.
API Client#
- class pyroclient.client.Client(token: str, host: str = 'https://api.pyronear.org', timeout: int = 10, **kwargs)[source]#
Isometric Python client for Pyronear wildfire detection API
- Parameters
token – your personal API token
endpoint – the host for your instance of pyronear API
timeout (int) – number of seconds before request timeout
kwargs – optional parameters of requests.post
- create_detection(media: bytes, bboxes: List[Tuple[float, float, float, float, float]], pose_id: int, crops: Optional[List[bytes]] = None, recorded_at: Optional[str] = None, temporal_model_scores: Optional[List[float]] = None) Response[source]#
Notify the detection of a wildfire on the picture taken by a camera.
>>> from pyroclient import Client >>> api_client = Client("MY_CAM_TOKEN") >>> with open("path/to/my/file.ext", "rb") as f: data = f.read() >>> response = api_client.create_detection(data, bboxes=[(.1,.1,.5,.8,.5)], pose_id=12)
- Parameters
media – byte data of the picture
bboxes – list of tuples where each tuple is a relative coordinate in order xmin, ymin, xmax, ymax, conf. An empty list reports a frame with no detection: the API attaches it to recently seen sequences of the pose (keeping their frame timeline continuous) and stores nothing otherwise (204).
pose_id – pose_id of the detection
crops – optional list of cropped pictures, one per bbox (must align with bboxes). Each crop frames a single object, so its length must equal that of bboxes.
recorded_at – optional ISO 8601 timestamp of when the image was captured on-device. Timezone-aware values are converted to UTC server-side; defaults to server now if omitted.
temporal_model_scores – optional smoke probabilities (0 to 1) from the temporal model run on the device, one per bbox (must align with bboxes). When given, the API applies its own threshold to them instead of scoring the sequences itself.
- Returns
HTTP response
- create_occlusion_mask(pose_id: int, mask: str) Response[source]#
Create a create occlusion_mask for a pose
>>> api_client.create_occlusion_mask(pose_id=1, mask="(0.1,0.1,0.9,0.9)")
- create_pose(camera_id: int, azimuth: float, patrol_id: Optional[int] = None, active: bool = True) Response[source]#
Create a pose for a camera
>>> api_client.create_pose(camera_id=1, azimuth=120.5, patrol_id=3)
- delete_occlusion_mask(mask_id: int) Response[source]#
Delete an occlusion mask
>>> api_client.delete_occlusion_mask(mask_id=1)
- fetch_cameras() Response[source]#
List the cameras accessible to the authenticated user. By default, only trustable cameras are returned.
>>> from pyroclient import client >>> api_client = Client("MY_USER_TOKEN") >>> response = api_client.fetch_cameras()
- Returns
HTTP response
- fetch_detections(limit: int = 100, offset: int = 0) Response[source]#
List a page of detections accessible to the authenticated user.
Pages default to 100 rows (maximum 500), ordered by ID. Advance offset to fetch more.
>>> from pyroclient import client >>> api_client = Client("MY_USER_TOKEN") >>> response = api_client.fetch_detections()
- Returns
HTTP response
- fetch_latest_sequences() Response[source]#
List the latest sequences accessible to the authenticated user
>>> from pyroclient import client >>> api_client = Client("MY_USER_TOKEN") >>> response = api_client.fetch_latest_sequences()
- Returns
HTTP response
- fetch_organizations() Response[source]#
List the organizations accessible to the authenticated user
>>> from pyroclient import client >>> api_client = Client("MY_USER_TOKEN") >>> response = api_client.fetch_organizations()
- Returns
HTTP response
- fetch_sequences_detections(sequence_id: int, limit: Optional[int] = None, desc: bool = True, with_crop: bool = True, sampling: int = 1, offset: int = 0) Response[source]#
List the detections of a sequence
>>> from pyroclient import client >>> api_client = Client("MY_USER_TOKEN") >>> response = api_client.fetch_sequences_detections(1)
- Parameters
sequence_id – ID of the associated sequence entry
limit – maximum number of detections to fetch. Unset (the default) lets the API pick: 10, or the size of the whole sampled span capped at 500 when sampling is set
desc – whether to order the detections by created_at in descending order
with_crop – whether to include the crop_url for detections that have a crop
sampling – keep one detection every N (1 = all, max 10000). The kept frames do not depend on desc. Leave limit unset to span the sequence, and read the X-Sampled-Total / X-Sampled-Truncated response headers
offset – raw detections to skip, from the oldest end when sampling. Page by advancing it in multiples of sampling
- Returns
HTTP response
- fetch_sequences_from_date(from_date: str, limit: int = 15, offset: int = 0) Response[source]#
List the sequences accessible to the authenticated user for a specific date
>>> from pyroclient import client >>> api_client = Client("MY_USER_TOKEN") >>> response = api_client.fetch_sequences_from_date("2023-07-04")
- Parameters
from_date – date of the sequences to fetch
limit – maximum number of sequences to fetch
offset – number of sequences to skip before starting to fetch
- Returns
HTTP response
- get_current_poses(camera_id: Optional[int] = None) Response[source]#
Fetch poses for the authenticated camera.
For admin/agent tokens, provide camera_id to retrieve poses via the camera endpoint.
- get_detection_url(detection_id: int) Response[source]#
Retrieve the URL of the media linked to a detection
>>> from pyroclient import client >>> api_client = Client("MY_USER_TOKEN") >>> response = api_client.get_detection_url(1)
- Parameters
detection_id – ID of the associated detection entry
- Returns
HTTP response
- get_occlusion_mask(mask_id: int) Response[source]#
get mask from occlusion mask
>>> api_client.get_occlusion_mask(mask_id=1")
- heartbeat(timeout: Optional[int] = None) Response[source]#
Update the last ping of the camera
>>> from pyroclient import Client >>> api_client = Client("MY_CAM_TOKEN") >>> response = api_client.heartbeat()
- Parameters
timeout – request timeout in seconds for this call only; defaults to the client timeout
- Returns
HTTP response containing the update device info
- label_sequence(sequence_id: int, is_wildfire: str) Response[source]#
Update the label of a sequence made by a camera
>>> from pyroclient import client >>> api_client = Client("MY_USER_TOKEN") >>> response = api_client.label_sequence(1, is_wildfire="wildfire_smoke")
- Parameters
sequence_id – ID of the associated sequence entry
is_wildfire – whether this sequence is confirmed as a wildfire
- Returns
HTTP response
- list_pose_masks(pose_id: int) Response[source]#
List occlusion masks for a pose (given its pose_id)
>>> api_client.list_pose_masks(pose_id=1)
- patch_occlusion_mask(mask_id: int, mask: str) Response[source]#
Update an occlusion mask
>>> api_client.patch_occlusion_mask(mask_id=1, mask="(0.1,0.2,0.9,0.3)")
- patch_pose(pose_id: int, azimuth: Optional[float] = None, patrol_id: Optional[int] = None, active: Optional[bool] = None) Response#
Update a pose
>>> api_client.update_pose(pose_id=1, azimuth=90.0)
- unmatch_alert_sequence(alert_id: int, sequence_id: int) Response[source]#
Detach a sequence from an alert. If the sequence is no longer linked to any alert, a new alert is created for it.
>>> from pyroclient import client >>> api_client = Client("MY_USER_TOKEN") >>> response = api_client.unmatch_alert_sequence(1, 2)
- Parameters
alert_id – ID of the alert the sequence should be detached from
sequence_id – ID of the sequence to detach
- Returns
HTTP response
- update_last_image(media: bytes) Response[source]#
Update the last image of the camera
>>> from pyroclient import Client >>> api_client = Client("MY_CAM_TOKEN") >>> with open("path/to/my/file.ext", "rb") as f: data = f.read() >>> response = api_client.update_last_image(data)
- Returns
HTTP response containing the update device info
- update_pose(pose_id: int, azimuth: Optional[float] = None, patrol_id: Optional[int] = None, active: Optional[bool] = None) Response[source]#
Update a pose
>>> api_client.update_pose(pose_id=1, azimuth=90.0)
- update_pose_image(pose_id: int, media: bytes) Response[source]#
Update the image of a pose
>>> from pyroclient import Client >>> api_client = Client("MY_TOKEN") >>> with open("path/to/my/file.ext", "rb") as f: data = f.read() >>> response = api_client.update_pose_image(pose_id=1, media=data)
- Parameters
pose_id – ID of the pose
media – byte data of the image
- Returns
HTTP response containing the updated pose info