blueye.sdk.camera - Blueye SDK

Skip to content

# blueye.sdk.camera

## `` camera

Classes:

- `Camera` –

  Handles the camera functionality for the Blueye drone.

- `Overlay` –

  Control the overlay on videos and pictures.

- `Tilt` –

  Handles the camera tilt functionality for the Blueye drone.

### `` Camera

    Camera(
        parent_drone: Drone, is_guestport_camera: bool = False
    )

Handles the camera functionality for the Blueye drone.

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

- `is_guestport_camera` (`bool`, default: `False` ) –

  Whether this is a guestport camera.

Methods:

- `take_picture` –

  Take a still picture and store it locally on the drone.

Attributes:

- `bitrate` (`int`) –

  Set or get the video stream bitrate.

- `bitrate_still_picture` (`int`) –

  Set or get the bitrate for the still picture stream.

- `exposure` (`int`) –

  Set or get the camera exposure.

- `framerate` (`int`) –

  Set or get the camera frame rate.

- `hue` (`int`) –

  Set or get the camera hue.

- `is_recording` (`Optional[bool]`) –

  Get or set the camera recording state.

- `record_time` (`Optional[int]`) –

  Get the duration of the current camera recording.

- `recording_resolution` (`Resolution`) –

  Set or get the camera recording resolution.

- `resolution` (`int`) –

  Set or get the camera resolution.

- `stream_resolution` (`Resolution`) –

  Set or get the camera stream resolution.

- `whitebalance` (`int`) –

  Set or get the camera white balance.

Source code in `blueye/sdk/camera.py`

    752
    753
    754
    755
    756
    757
    758
    759
    760
    761
    762
    763
    764
    765
    766
    767
    768
    769
    def __init__(self, parent_drone: Drone, is_guestport_camera: bool = False):
        """Initialize the Camera class.

        Args:
            parent_drone (Drone): The parent drone instance.
            is_guestport_camera (bool, optional): Whether this is a guestport camera.
        """
        self._parent_drone = parent_drone
        self._is_guestport_camera = is_guestport_camera
        self._camera_type = (
            blueye.protocol.Camera.CAMERA_GUESTPORT
            if is_guestport_camera
            else blueye.protocol.Camera.CAMERA_MAIN
        )
        if not self._is_guestport_camera:
            self.tilt = Tilt(parent_drone)
            self.overlay = Overlay(parent_drone)
        self._camera_parameters = None

#### `` bitrate `property` `writable`

    bitrate: int

Set or get the video stream bitrate.

Parameters:

- `bitrate` (`int`) –

  Set the video stream bitrate in bits, valid values are in range (1 000 000 .. 16 000 000).

Returns:

- `int` –

  The H264 video stream bitrate.

#### `` bitrate_still_picture `property` `writable`

    bitrate_still_picture: int

Set or get the bitrate for the still picture stream.

Parameters:

- `bitrate` (`int`) –

  Set the still picture stream bitrate in bits, valid values are in range (1 000 000 .. 300 000 000). Default value is 100 000 000.

Returns:

- `int` –

  The still picture stream bitrate.

#### `` exposure `property` `writable`

    exposure: int

Set or get the camera exposure.

Parameters:

- `exposure` (`int`) –

  Set the camera exposure time. Unit is thousandths of a second, ie. 5 = 5s/1000. Valid values are in the range (1 .. 5000) or -1 for auto exposure.

Returns:

- `int` –

  The camera exposure.

#### `` framerate `property` `writable`

    framerate: int

Set or get the camera frame rate.

Parameters:

- `framerate` (`int`) –

  Set the camera frame rate in frames per second. Valid values are 25 or 30.

Returns:

- `int` –

  The camera frame rate.

#### `` hue `property` `writable`

    hue: int

Set or get the camera hue.

Parameters:

- `hue` (`int`) –

  Set the camera hue. Valid values are in the range (-40..40).

Returns:

- `int` –

  The camera hue.

#### `` is_recording `property` `writable`

    is_recording: Optional[bool]

Get or set the camera recording state.

Parameters:

- `start_recording` (`bool`) –

  Set to True to start a recording, set to False to stop the current recording.

Returns:

- `Optional[bool]` –

  True if the camera is currently recording, False if not. Returns None if the SDK hasn't received a RecordState telemetry message.

Warns:

- `RuntimeWarning` –

  If no recording state telemetry data is received.

#### `` record_time `property`

    record_time: Optional[int]

Get the duration of the current camera recording.

Returns:

- `Optional[int]` –

  The length in seconds of the current recording, -1 if the camera is not currently recording. Returns None if the SDK hasn't received a RecordState telemetry message.

#### `` recording_resolution `property` `writable`

    recording_resolution: Resolution

Set or get the camera recording resolution.

For drones running Blunux version < 4.4.1 this is the same as the `resolution` property.

Returns:

- `Resolution` –

  The camera recording resolution.

#### `` resolution `property` `writable`

    resolution: int

Set or get the camera resolution.

Parameters:

- `resolution` (`int`) –

  Set the camera in vertical pixels. Valid values are 720 or 1080.

Returns:

- `int` –

  The camera resolution.

#### `` stream_resolution `property` `writable`

    stream_resolution: Resolution

Set or get the camera stream resolution.

For drones running blunux version < 4.4.1 this is the same as the `resolution` property.

Parameters:

- `resolution` (`Resolution`) –

  Set the camera stream resolution.

Raises:

- `ValueError` –

  If the resolution is not a valid `blueye.protocol.Resolution` type

Returns:

- `Resolution` –

  The camera stream resolution

#### `` whitebalance `property` `writable`

    whitebalance: int

Set or get the camera white balance.

Parameters:

- `white_balance` (`int`) –

  Set the camera white balance. Valid values are in the range (2800..9300) or -1 for auto white balance.

Returns:

- `int` –

  The camera white balance.

#### `` take_picture

    take_picture()

Take a still picture and store it locally on the drone.

These pictures can be downloaded with the Blueye App, or by any WebDAV compatible client.

Source code in `blueye/sdk/camera.py`

    1070
    1071
    1072
    1073
    1074
    1075
    def take_picture(self):
        """Take a still picture and store it locally on the drone.

        These pictures can be downloaded with the Blueye App, or by any WebDAV compatible client.
        """
        self._parent_drone._ctrl_client.take_still_picture()

### `` Overlay

    Overlay(parent_drone: Drone)

Control the overlay on videos and pictures.

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

Methods:

- `delete_logo` –

  Delete the user uploaded logo from the drone.

- `download_logo` –

  Download the original user uploaded logo (PNG or JPG).

- `upload_logo` –

  Upload user selectable logo for watermarking videos and pictures.

Attributes:

- `altitude_enabled` (`bool`) –

  Get or set the state of the altitude overlay.

- `cp_probe_enabled` (`bool`) –

  Get or set the state of the CP probe overlay.

- `date_enabled` (`bool`) –

  Get or set the state of the date overlay.

- `date_format` (`str`) –

  Get or set the format string for the time displayed in the overlay.

- `depth_enabled` (`bool`) –

  Get or set the state of the depth overlay.

- `depth_unit` (`DepthUnit`) –

  Get or set the depth unit for the overlay.

- `distance_enabled` (`bool`) –

  Get or set the state of the distance overlay.

- `drone_location_enabled` (`bool`) –

  Get or set the state of the drone location overlay.

- `font_size` (`FontSize`) –

  Get or set the font size for the overlay.

- `gamma_ray_measurement_enabled` (`bool`) –

  Get or set the state of the gamma-ray measurement overlay.

- `heading_enabled` (`bool`) –

  Get or set the state of the heading overlay.

- `logo` (`LogoType`) –

  Get or set logo overlay selection.

- `margin_height` (`int`) –

  Get or set the margin height for the overlay.

- `margin_width` (`int`) –

  Get or set the margin width for the overlay.

- `shading` (`float`) –

  Get or set the pixel intensity to subtract from text background.

- `subtitle` (`str`) –

  Get or set the subtitle for the overlay.

- `temperature_enabled` (`bool`) –

  Get or set the state of the temperature overlay.

- `temperature_unit` (`TemperatureUnit`) –

  Get or set the temperature unit for the overlay.

- `thickness_enabled` (`bool`) –

  Get or set the state of the thickness overlay.

- `thickness_unit` (`ThicknessUnit`) –

  Get or set the thickness unit for the overlay.

- `tilt_enabled` (`bool`) –

  Get or set the state of the tilt overlay.

- `timezone_offset` (`int`) –

  Get or set the timezone offset for the overlay.

- `title` (`str`) –

  Get or set the title for the overlay.

Source code in `blueye/sdk/camera.py`

    103
    104
    105
    106
    107
    108
    109
    110
    def __init__(self, parent_drone: Drone):
        """Initialize the Overlay class.

        Args:
            parent_drone (Drone): The parent drone instance.
        """
        self._parent_drone = parent_drone
        self._overlay_parametres = None

#### `` altitude_enabled `property` `writable`

    altitude_enabled: bool

Get or set the state of the altitude overlay.

Returns:

- `bool` –

  The current state of the altitude overlay.

Parameters:

- `enable_altitude` (`bool`) –

  True to enable the altitude overlay, False to disable it.

#### `` cp_probe_enabled `property` `writable`

    cp_probe_enabled: bool

Get or set the state of the CP probe overlay.

Returns:

- `bool` –

  The current state of the CP probe overlay.

Parameters:

- `enable_cp_probe` (`bool`) –

  True to enable the CP probe overlay, False to disable it.

#### `` date_enabled `property` `writable`

    date_enabled: bool

Get or set the state of the date overlay.

Returns:

- `bool` –

  The current state of the date overlay.

Parameters:

- `enable_date` (`bool`) –

  True to enable the date overlay, False to disable it.

#### `` date_format `property` `writable`

    date_format: str

Get or set the format string for the time displayed in the overlay.

Must be a string containing only ASCII characters, with a max length of 63 characters.

The format codes are defined by the C89 standard, see https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes for an overview of the available codes.

Returns:

- `str` –

  The current date format.

Parameters:

- `input_format_str` (`str`) –

  The date format string to set.

Warns:

- `RuntimeWarning` –

  If the date format is too long or contains non-ASCII characters.

#### `` depth_enabled `property` `writable`

    depth_enabled: bool

Get or set the state of the depth overlay.

Returns:

- `bool` –

  The current state of the depth overlay.

Parameters:

- `enable_depth` (`bool`) –

  True to enable the depth overlay, False to disable it.

#### `` depth_unit `property` `writable`

    depth_unit: DepthUnit

Get or set the depth unit for the overlay.

Returns:

- `DepthUnit` –

  The current depth unit.

Parameters:

- `unit` (`DepthUnit`) –

  The depth unit to set.

Warns:

- `RuntimeWarning` –

  If the unit is not an instance of blueye.protocol.DepthUnit.

#### `` distance_enabled `property` `writable`

    distance_enabled: bool

Get or set the state of the distance overlay.

Returns:

- `bool` –

  The current state of the distance overlay.

Parameters:

- `enable_distance` (`bool`) –

  True to enable the distance overlay, False to disable it.

#### `` drone_location_enabled `property` `writable`

    drone_location_enabled: bool

Get or set the state of the drone location overlay.

Returns:

- `bool` –

  The current state of the drone location overlay.

Parameters:

- `enable_drone_location` (`bool`) –

  True to enable the drone location overlay, False to disable it.

#### `` font_size `property` `writable`

    font_size: FontSize

Get or set the font size for the overlay.

Needs to be an instance of the `blueye.protocol.FontSize` enum.

Returns:

- `FontSize` –

  The current font size.

Parameters:

- `size` (`FontSize`) –

  The font size to set.

Warns:

- `RuntimeWarning` –

  If the font size is not an instance of blueye.protocol.FontSize.

#### `` gamma_ray_measurement_enabled `property` `writable`

    gamma_ray_measurement_enabled: bool

Get or set the state of the gamma-ray measurement overlay.

Returns:

- `bool` –

  The current state of the gamma-ray measurement overlay.

Parameters:

- `enable_gamma_ray_measurement` (`bool`) –

  True to enable the gamma-ray measurement overlay, False to disable it.

#### `` heading_enabled `property` `writable`

    heading_enabled: bool

Get or set the state of the heading overlay.

Returns:

- `bool` –

  The current state of the heading overlay.

Parameters:

- `enable_heading` (`bool`) –

  True to enable the heading overlay, False to disable it.

#### `` logo `property` `writable`

    logo: LogoType

Get or set logo overlay selection.

Returns:

- `LogoType` –

  The current logo type.

Parameters:

- `logo_type` (`LogoType`) –

  The logo type.

Warns:

- `RuntimeWarning` –

  If the logo type is not an instance of blueye.protocol.LogoType.

#### `` margin_height `property` `writable`

    margin_height: int

Get or set the margin height for the overlay.

The amount of pixels to use as margin on the top and bottom side of the overlay.

Returns:

- `int` –

  The current margin height.

Parameters:

- `height` (`int`) –

  The margin height to set. Needs to be a positive integer.

#### `` margin_width `property` `writable`

    margin_width: int

Get or set the margin width for the overlay.

The amount of pixels to use as margin on the right and left side of the overlay.

Returns:

- `int` –

  The current margin width.

Parameters:

- `width` (`int`) –

  The margin width to set. Needs to be a positive integer.

Warns:

- `RuntimeWarning` –

  If the margin width is not a positive integer.

#### `` shading `property` `writable`

    shading: float

Get or set the pixel intensity to subtract from text background.

Returns:

- `float` –

  The current shading intensity.

Parameters:

- `intensity` (`float`) –

  The shading intensity to set. Valid range is 0.0 to 1.0. 0 is transparent, 1 is black.

Warns:

- `RuntimeWarning` –

  If the shading intensity is not a float between 0.0 and 1.0.

#### `` subtitle `property` `writable`

    subtitle: str

Get or set the subtitle for the overlay.

The subtitle needs to be a string of only ASCII characters with a maximum length of 63 characters.

Set to an empty string to disable the subtitle.

Returns:

- `str` –

  The current subtitle.

Parameters:

- `input_subtitle` (`str`) –

  The subtitle to set. Set to an empty string to disable. Truncated to 63 characters if longer.

Warns:

- `RuntimeWarning` –

  If the subtitle is too long or contains non-ASCII characters.

#### `` temperature_enabled `property` `writable`

    temperature_enabled: bool

Get or set the state of the temperature overlay.

Returns:

- `bool` –

  The current state of the temperature overlay.

Parameters:

- `enable_temperature` (`bool`) –

  True to enable the temperature overlay, False to disable it.

#### `` temperature_unit `property` `writable`

    temperature_unit: TemperatureUnit

Get or set the temperature unit for the overlay.

Returns:

- `TemperatureUnit` –

  The current temperature unit.

Parameters:

- `unit` (`TemperatureUnit`) –

  The temperature unit to set.

Warns:

- `RuntimeWarning` –

  If the unit is not an instance of blueye.protocol.TemperatureUnit.

#### `` thickness_enabled `property` `writable`

    thickness_enabled: bool

Get or set the state of the thickness overlay.

Returns:

- `bool` –

  The current state of the thickness overlay.

Parameters:

- `enable_thickness` (`bool`) –

  True to enable the thickness overlay, False to disable it.

#### `` thickness_unit `property` `writable`

    thickness_unit: ThicknessUnit

Get or set the thickness unit for the overlay.

Returns:

- `ThicknessUnit` –

  The current thickness unit.

Parameters:

- `unit` (`ThicknessUnit`) –

  The thickness unit to set.

Warns:

- `RuntimeWarning` –

  If the unit is not an instance of blueye.protocol.ThicknessUnit.

#### `` tilt_enabled `property` `writable`

    tilt_enabled: bool

Get or set the state of the tilt overlay.

Returns:

- `bool` –

  The current state of the tilt overlay.

Parameters:

- `enable_tilt` (`bool`) –

  True to enable the tilt overlay, False to disable it.

#### `` timezone_offset `property` `writable`

    timezone_offset: int

Get or set the timezone offset for the overlay.

Set to the number of minutes (either positive or negative) the timestamp should be offset.

Returns:

- `int` –

  The current timezone offset.

Parameters:

- `offset` (`int`) –

  The timezone offset to set.

#### `` title `property` `writable`

    title: str

Get or set the title for the overlay.

The title needs to be a string of only ASCII characters with a maximum length of 63 characters.

Set to an empty string to disable title.

Returns:

- `str` –

  The current title.

Parameters:

- `input_title` (`str`) –

  The title to set. Truncated to 63 characters if longer.

Warns:

- `RuntimeWarning` –

  If the title is too long or contains non-ASCII characters.

#### `` delete_logo

    delete_logo(timeout: float = 1.0)

Delete the user uploaded logo from the drone.

Parameters:

- `timeout` (`float`, default: `1.0` ) –

  The timeout for the delete request.

Raises:

- `HTTPError` –

  If an error occurs during deletion.

- `ConnectTimeout` –

  If unable to create a connection within the specified timeout.

Source code in `blueye/sdk/camera.py`

    734
    735
    736
    737
    738
    739
    740
    741
    742
    743
    744
    745
    746
    def delete_logo(self, timeout: float = 1.0):
        """Delete the user uploaded logo from the drone.

        Args:
            timeout (float): The timeout for the delete request.

        Raises:
            requests.exceptions.HTTPError: If an error occurs during deletion.
            requests.exceptions.ConnectTimeout: If unable to create a connection within the
                                                specified timeout.
        """
        response = requests.delete(f"http://{self._parent_drone._ip}/asset/logo", timeout=timeout)
        response.raise_for_status()

#### `` download_logo

    download_logo(output_directory='.', timeout: float = 1.0)

Download the original user uploaded logo (PNG or JPG).

Select the download directory with the output_directory parameter.

Parameters:

- `output_directory` (`str`, default: `'.'` ) –

  The directory to save the downloaded logo.

- `timeout` (`float`, default: `1.0` ) –

  The timeout for the download request.

Raises:

- `HTTPError` –

  If no custom logo is uploaded.

- `ConnectTimeout` –

  If unable to create a connection within the specified timeout.

Source code in `blueye/sdk/camera.py`

    714
    715
    716
    717
    718
    719
    720
    721
    722
    723
    724
    725
    726
    727
    728
    729
    730
    731
    732
    def download_logo(self, output_directory=".", timeout: float = 1.0):
        """Download the original user uploaded logo (PNG or JPG).

        Select the download directory with the output_directory parameter.

        Args:
            output_directory (str): The directory to save the downloaded logo.
            timeout (float): The timeout for the download request.

        Raises:
            requests.exceptions.HTTPError: If no custom logo is uploaded.
            requests.exceptions.ConnectTimeout: If unable to create a connection within the
                                                specified timeout.
        """
        response = requests.get(f"http://{self._parent_drone._ip}/asset/logo", timeout=timeout)
        response.raise_for_status()
        filename = re.findall('filename="(.+)"', response.headers["Content-Disposition"])[0]
        with open(f"{output_directory}/{filename}", "wb") as f:
            f.write(response.content)

#### `` upload_logo

    upload_logo(path_to_logo: str, timeout: float = 1.0)

Upload user selectable logo for watermarking videos and pictures.

Set the logo-property to `blueye.protocol.LogoType.LOG_TYPE_CUSTOM` to enable this logo.

Allowed filetype: JPG or PNG. Max resolution: 2000 px. Max file size: 5 MB.

Parameters:

- `path_to_logo` (`str`) –

  The path to the logo file.

- `timeout` (`float`, default: `1.0` ) –

  The timeout for the upload request.

Raises:

- `HTTPError` –

  If the file is invalid (status code 400).

- `ConnectTimeout` –

  If unable to create a connection within the specified timeout.

Source code in `blueye/sdk/camera.py`

    690
    691
    692
    693
    694
    695
    696
    697
    698
    699
    700
    701
    702
    703
    704
    705
    706
    707
    708
    709
    710
    711
    712
    def upload_logo(self, path_to_logo: str, timeout: float = 1.0):
        """Upload user selectable logo for watermarking videos and pictures.

        Set the logo-property to `blueye.protocol.LogoType.LOG_TYPE_CUSTOM` to enable this logo.

        Allowed filetype: JPG or PNG.
        Max resolution: 2000 px.
        Max file size: 5 MB.

        Args:
            path_to_logo (str): The path to the logo file.
            timeout (float, optional): The timeout for the upload request.

        Raises:
            requests.exceptions.HTTPError: If the file is invalid (status code 400).
            requests.exceptions.ConnectTimeout: If unable to create a connection within the
                                                specified timeout.
        """
        with open(path_to_logo, "rb") as f:
            url = f"http://{self._parent_drone._ip}/asset/logo"
            files = {"image": f}
            response = requests.post(url, files=files, timeout=timeout)
        response.raise_for_status()

### `` Tilt

    Tilt(parent_drone: Drone)

Handles the camera tilt functionality for the Blueye drone.

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

Methods:

- `set_velocity` –

  Set the speed and direction of the camera tilt.

Attributes:

- `angle` (`Optional[float]`) –

  Return the current angle of the camera tilt.

- `stabilization_enabled` (`Optional[bool]`) –

  Get the state of active camera stabilization.

Source code in `blueye/sdk/camera.py`

    23
    24
    25
    26
    27
    28
    29
    def __init__(self, parent_drone: Drone):
        """Initialize the Tilt class.

        Args:
            parent_drone (Drone): The parent drone instance.
        """
        self._parent_drone = parent_drone

#### `` angle `property`

    angle: Optional[float]

Return the current angle of the camera tilt.

Returns:

- `Optional[float]` –

  The current angle of the camera tilt.

Raises:

- `RuntimeError` –

  If the connected drone does not have the tilt option.

#### `` stabilization_enabled `property` `writable`

    stabilization_enabled: Optional[bool]

Get the state of active camera stabilization.

Returns:

- `Optional[bool]` –

  The current state of active camera stabilization.

Raises:

- `RuntimeError` –

  If the connected drone does not have the tilt option.

#### `` set_velocity

    set_velocity(velocity: float)

Set the speed and direction of the camera tilt.

Parameters:

- `velocity` (`float`) –

  Speed and direction of the tilt. 1 is max speed up, -1 is max speed down.

Raises:

- `RuntimeError` –

  If the connected drone does not have the tilt option.

Source code in `blueye/sdk/camera.py`

    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    def set_velocity(self, velocity: float):
        """Set the speed and direction of the camera tilt.

        Args:
            velocity: Speed and direction of the tilt. 1 is max speed up, -1 is max speed down.

        Raises:
            RuntimeError: If the connected drone does not have the tilt option.
        """
        self._verify_tilt_in_features()
        self._parent_drone._ctrl_client.set_tilt_velocity(velocity)