UIImage#

The UIImage class represents an image object that can be loaded from a file, binary data, or a Base64 string. It provides APIs for image encoding (PNG/JPEG), format conversion, and UI display. A UIImage instance can be directly displayed in an Image component or used together with the Data class for storage, uploading, or encryption.

Overview#

UIImage is the core image-handling class in the scripting environment. You can use it to:

• Load images from local files, binary data, or Base64 strings
• Retrieve pixel dimensions of an image
• Convert image formats (PNG/JPEG)
• Generate Base64-encoded image data
• Display images in the UI using the <Image> component
• Support automatic light/dark mode switching with dynamic image sources

Properties#

width: number#

The width of the image in pixels.

1const image = UIImage.fromFile("/path/to/image.png")
2console.log(image?.width)

height: number#

The height of the image in pixels.

1const image = UIImage.fromFile("/path/to/image.png")
2console.log(image?.height)

Instance Methods#

toJPEGData(compressionQuality?: number): Data | null#

Converts the image to JPEG data.

• Parameters:

  • compressionQuality (optional): The JPEG compression quality, ranging from 0 (maximum compression) to 1 (lossless). Default is 1.

• Returns:

  • A Data instance containing the JPEG data, or null if conversion fails.

Example:

1const image = UIImage.fromFile("/path/to/photo.png")
2const jpegData = image?.toJPEGData(0.8)
3if (jpegData) {
4  console.log(`JPEG data size: ${jpegData.length} bytes`)
5}

toPNGData(): Data | null#

Converts the image to PNG data.

• Returns:

  • A Data instance containing PNG data, or null if conversion fails.

Example:

1const image = UIImage.fromFile("/path/to/logo.png")
2const pngData = image?.toPNGData()

toJPEGBase64String(compressionQuality?: number): string | null#

Converts the image to a Base64-encoded JPEG string.

• Parameters:

  • compressionQuality (optional): JPEG compression quality (0–1, default is 1).

• Returns:

  • A Base64-encoded string, or null if conversion fails.

Example:

1const image = UIImage.fromFile("/path/to/avatar.jpg")
2const base64 = image?.toJPEGBase64String(0.7)
3if (base64) {
4  console.log(base64.slice(0, 100) + "...")
5}

toPNGBase64String(): string | null#

Converts the image to a Base64-encoded PNG string.

• Returns:

  • A Base64-encoded string, or null if conversion fails.

Example:

1const image = UIImage.fromFile("/path/to/icon.png")
2const base64 = image?.toPNGBase64String()

Static Methods#

UIImage.fromFile(filePath: string): UIImage | null#

Creates a UIImage instance from a file path.

• Parameters:

  • filePath: The absolute path to the image file (supports PNG, JPG, JPEG).

• Returns:

  • A UIImage instance if successful, or null if loading fails.

Example:

1const image = UIImage.fromFile("/path/to/images/sample.jpg")
2if (image) {
3  console.log(`Width: ${image.width}, Height: ${image.height}`)
4}

UIImage.fromData(data: Data): UIImage | null#

Creates a UIImage instance from binary data.

• Parameters:

  • data: A Data instance containing valid PNG or JPEG data.

• Returns:

  • A UIImage instance if successful, or null if the data is invalid.

Example:

1const fileData = Data.fromFile("/path/to/picture.png")
2const image = fileData ? UIImage.fromData(fileData) : null

UIImage.fromBase64String(base64String: string): UIImage | null#

Creates a UIImage instance from a Base64-encoded string.

• Parameters:

  • base64String: The Base64-encoded string representing image data.

• Returns:

  • A UIImage instance if successful, or null if decoding fails.

Example:

1const base64 = "iVBORw0KGgoAAAANSUhEUgAA..."
2const image = UIImage.fromBase64String(base64)

Using UIImage in the UI#

UIImage can be displayed directly in the <Image> component.

Component Definition#

1declare const Image: FunctionComponent<UIImageProps>

Props Definition#

1type UIImageProps = {
2  image: UIImage | DynamicImageSource<UIImage>
3}

Dynamic Image Type#

1type DynamicImageSource<T> = {
2  light: T
3  dark: T
4}

Used to define separate images for light and dark modes.

Example: Display a Single Image#

1const image = UIImage.fromFile("/path/to/avatar.png")
2<Image image={image} />

Example: Light and Dark Mode Support#

1const lightImage = UIImage.fromFile("/path/to/light-logo.png")
2const darkImage = UIImage.fromFile("/path/to/dark-logo.png")
3
4<Image image={{ light: lightImage, dark: darkImage }} />

Common Use Cases#

1. Convert an Image to Base64#

1const image = UIImage.fromFile("/path/to/image.png")
2const base64 = image?.toPNGBase64String()

2. Compress an Image and Save as JPEG#

1const image = UIImage.fromFile("/path/to/photo.jpg")
2const jpegData = image?.toJPEGData(0.6)
3if (jpegData) {
4  // write jpegData to a file
5}

3. Restore and Display Image from Base64#

1const base64 = "iVBORw0KGgoAAAANSUhEUgAA..."
2const image = UIImage.fromBase64String(base64)
3<Image image={image} />

4. Convert PNG to JPEG and Upload#

1const image = UIImage.fromFile("/path/to/logo.png")
2const jpegData = image?.toJPEGData(0.8)
3if (jpegData) {
4  const response = await fetch("https://example.com/upload", {
5    method: "POST",
6    body: jpegData.toUint8Array()
7  })
8}

Summary#

The UIImage class is the foundation of image handling in the Scripting environment. It supports:

• Loading from file paths, binary data, or Base64 strings
• Retrieving image dimensions
• Format conversion between PNG and JPEG
• Generating Base64 strings for sharing or storage
• Direct UI rendering with light/dark mode adaptability