Sending Content

def send_image(path: Union[str, Path], resize_method: Union[str, ResizeMethod] = ResizeMethod.CROP, device_info: Optional[DeviceInfo] = None, save_slot: int = 0):
    """
    Send an image or animation.
    Supports `.png`, `.webp`, `.jpg`, `.jpeg`, `.bmp`, `.tiff`, `.gif` and `.heic, .heif` if pillow-heif library is installed.

    Args:
        path: File path.
        device_info: Device information (injected automatically by DeviceSession).
        resize_method: Resize method - 'crop' (default) or 'fit'. 
                  'crop' will fill the entire target area and crop excess.
                  'fit' will fit the entire image with black padding.
        save_slot: If >= 1, will save to that slot.

    Note:
        If device_info is available, the image will be automatically resized
        to match the target device dimensions if necessary.
    """

    # Input normalization
    if isinstance(resize_method, str):
        resize_method = ResizeMethod(resize_method)
    if isinstance(path, str):
        path = Path(path)
    save_slot = int(save_slot)

    # Load image data
    if path.exists() and path.is_file():
        with open(path, "rb") as f:
            file_bytes = f.read()
        file_bytes, is_gif = _process_loaded_bytes(file_bytes, path.suffix.lower())
    else:
        raise ValueError(f"File not found: {path}")

    # Resize image if device_info is available
    if device_info is not None:
        file_bytes = _resize_image(file_bytes, is_gif, device_info.width, device_info.height, resize_method)
    else:
        logger.warning("Device info not provided; skipping image resizing.")

    return _build_send_plan(file_bytes, is_gif, plan_name="send_image", save_slot=save_slot)

def send_image_hex(hex_string: Union[str, bytes], file_extension: str, resize_method: Union[str, ResizeMethod] = ResizeMethod.CROP, device_info: Optional[DeviceInfo] = None, save_slot: int = 0):
    """
    Send an image or animation from a hexadecimal string.

    Args:
        hex_string: Hexadecimal representation of image data.
        file_extension: File extension to indicate image type (e.g. `.png`, `.gif`).
        device_info: Device information (injected automatically by DeviceSession).
        resize_method: Resize method - 'crop' (default) or 'fit'. 
                  'crop' will fill the entire target area and crop excess.
                  'fit' will fit the entire image with black padding.
        save_slot: If >= 1, will save to that slot.
    """
    # Input normalization
    if isinstance(resize_method, str):
        resize_method = ResizeMethod(resize_method)

    # Load image data from hex string
    file_bytes, is_gif = _load_from_hex_string(hex_string, file_extension)

    # Resize image if device_info is available
    if device_info is not None:
        file_bytes = _resize_image(file_bytes, is_gif, device_info.width, device_info.height, resize_method)
    else:
        logger.warning("Device info not provided; skipping image resizing.")

    return _build_send_plan(file_bytes, is_gif, plan_name="send_image_hex", save_slot=save_slot)

def send_text(text: str,
              rainbow_mode: int = 0,
              animation: Union[TextAnimation, str, int] = TextAnimation.STATIC,
              save_slot: int = 0,
              speed: int = 80,
              color: str = "ffffff",
              bg_color: Optional[str] = None,
              font: Union[str, FontConfig] = "UNIFONT",
              char_height: Optional[int] = None,
              device_info: Optional[DeviceInfo] = None
              ) -> SendPlan:
    """
    Send a text to the device with configurable parameters.
    If emojis are included in the text, they will be rendered using Twemoji.

    Args:
        text (str): The text to send. Supports inline color tags (e.g. '[#ff0000]Hello[/]').
        rainbow_mode (int, optional): Rainbow mode (0-9). Defaults to 0.
        animation (TextAnimation | str | int, optional): Animation type (e.g. TextAnimation.SCROLL_LEFT, 'scroll_left', 1). Defaults to TextAnimation.STATIC.
        save_slot (int, optional): Save slot (1-10). Defaults to 1.
        speed (int, optional): Animation speed (0-100). Defaults to 80.
        color (str, optional): Default text color in hex. Defaults to "ffffff".
        bg_color (str, optional): Background color in hex (e.g., "ff0000"). Defaults to None.
        font (str | FontConfig, optional): Font name, file path, key-value string, or FontConfig. Defaults to "UNIFONT".
        char_height (int, optional): Character height. Auto-detected from device_info if not specified.
        device_info (DeviceInfo, optional): Device information (injected automatically).

    Raises:
        ValueError: If an invalid animation is selected or parameters are out of range.
    """
    # 0. Parse animation parameter
    anim = parse_animation(animation)

    # 1. Resolve font configuration and character height
    font_config = resolve_font_config(font)

    if char_height is None:
        if device_info is not None:
            char_height = get_char_height_from_device(device_info)
        else:
            raise ValueError("char_height must be specified if device_info is not provided")

    char_height = int(char_height)

    # 2. Build RenderContext from FontConfig
    context = RenderContext(
        char_height=char_height,
        font_path=font_config.path,
        font_size=font_config.font_size if font_config.font_size is not None else char_height,
        font_offset=font_config.offset,
        pixel_threshold=font_config.pixel_threshold,
    )

    resolved_var_width = font_config.var_width


    # 4. Handle inline color tags
    if resolved_var_width:
        if has_color_tags(text):
            logger.warning("Color tags are not supported with var_width and will be ignored.")
            clean_text = strip_color_tags(text)
        else:
            clean_text = text
        char_colors = None
    else:
        clean_text, char_colors = parse_colored_text(text, color)

    # 5. Parse and validate colors
    color_bytes = parse_hex_color(color, "Color")
    bg_color_bytes = parse_hex_color(bg_color, "Background color") if bg_color is not None else None

    # 6. Validate parameter ranges
    checks = [
        (int(rainbow_mode), 0, 9, "Rainbow mode"),
        (int(save_slot), 0, 255, "Save slot"),
        (int(speed), 0, 100, "Speed"),
        (len(clean_text), 1, 500, "Text length"),
        (char_height, 1, 128, "Char height"),
    ]
    for param, min_val, max_val, name in checks:
        if not (min_val <= param <= max_val):
            raise ValueError(f"{name} must be between {min_val} and {max_val} (got {param})")

    if device_info and (device_info.height != 32 or device_info.width != 32):
        if anim in (TextAnimation.SCROLL_UP, TextAnimation.SCROLL_DOWN):
            raise ValueError("This animation is not supported with this font on non-32x32 devices.")

    # 7. Encode characters
    rtl = (anim == TextAnimation.SCROLL_RIGHT)

    if resolved_var_width:
        actual_chunk_width = 8 if char_height <= 20 else 16
        characters_bytes, num_chars = encode_text_chunked(
            clean_text, color_bytes, context, actual_chunk_width, reverse=rtl
        )
    else:
        characters_bytes = encode_text(
            clean_text, color_bytes, context, reverse=rtl, char_colors=char_colors
        )
        num_chars = len(clean_text)

    # 8. Assemble data payload and generate transport send plan
    properties = build_text_properties(anim.value, speed, rainbow_mode, color_bytes, bg_color_bytes)
    data_payload = bytes([num_chars]) + properties + characters_bytes

    return build_text_send_plan(data_payload, save_slot=int(save_slot))