Image

2026-11-03Loading rating…

1. Feature Description

RemoteImage is a component for displaying images, corresponding to ViewType.IMAGE_VIEW. It supports setting an image file name, scale type (ScaleType), and image tint, and combined with common properties it can achieve rounded, circular, stroked, or semi-transparent styles. It fits icons, diagrams, and photo thumbnails.

Image assets must be uploaded to Pilot via file transfer first, then referenced by file name. Create it via RemoteViewHelper.createImage():

val image = helper.createImage()

2. Common Properties

The following properties are set via the corresponding setXxx() methods. Unless noted otherwise, if the component is already mounted, call syncToRemote() after changing a property to make it take effect on Pilot.

Size & Layout (inherited from RemoteViewProvider)

MethodParamsDescription
setWidthIntWidth (dp); special values RemoteView.MATCH_PARENT(-1) / WRAP_CONTENT(-2)
setHeightIntHeight (dp); same special values
setMinSizeminWidth: Int, minHeight: IntMinimum size (dp)
setPaddingleft, top, right, bottom: IntPadding (dp)
setVisibilityVisibilityTypeVisibility: VISIBLE / INVISIBLE / GONE
setAlphaFloatOpacity, 0.0 – 1.0
setEnabledBooleanWhether enabled

Background & Shape (inherited from RemoteViewProvider)

MethodParamsDescription
setBackgroundIntSolid background color (ARGB Int)
setBackgroundShapeShapeDescriptorBackground shape: fill / stroke / corner radius (use SHAPE_OVAL for a circle)

Image Properties

MethodParamsDescription
setImageFileNameStringImage file name (must be uploaded to Pilot via helper.pushImageFile(...) first)
setScaleTypeScaleTypeScale type: MATRIX / FIT_XY / FIT_START / FIT_CENTER / FIT_END / CENTER / CENTER_CROP / CENTER_INSIDE
setImageTintIntImage tint (ARGB Int), overlays a color mask on the image

3. Tips

  1. An image must be uploaded to Pilot before it can be referenced. Call helper.pushImageFile(filePath, callback) to upload the local image first, and only call setImageFileName(...) after the success callback (onSuccess), otherwise the Server cannot find the file and the image will not display.
  2. File names are case-sensitive. The name passed to setImageFileName must exactly match the uploaded file name (including extension, e.g. sea_view.webp); a case mismatch causes reference failure.
  3. Tint and background colors must be ARGB Int. setImageTint / setBackground accept an Int color value (e.g. 0x4DFFCC00.toInt()). Do not pass "#RRGGBB", "0xAARRGGBB", or R.color.xxx.
  4. Use ShapeDescriptor's SHAPE_OVAL for circular images and set equal width/height; use cornerRadius(...) for rounded corners and stroke(width, color) for a border.
  5. Call syncToRemote() after changing a mounted component's properties. setXxx only updates the local cache; syncToRemote() batch-syncs to Pilot. If you configure properties before mounting, no extra call is needed.
  6. ImageView does not support text overlay (the render layer silently ignores text properties). To overlay text on an image, place an Image and a Text together inside a ConstraintLayout and set constraints.

4. Sample Code

In each group below, the code sample is on the left and the corresponding Pilot-side rendered preview is on the right.

01 Component Types (square / rounded / circular)

// The image must be uploaded to Pilot; reference the file name only after success
helper.pushImageFile(localImagePath, object : CommonCallbacks.CompletionCallbackWithProgress<Double> {
    override fun onProgressUpdate(progress: Double) {}
    override fun onSuccess() {
        // Create and configure the image after a successful upload
        buildImages()
    }
    override fun onFailure(error: IDJIError) {}
})

fun buildImages() {
    val imageFileName = "sea_view.webp" // case must match the uploaded file

    // Square image
    val square = helper.createImage().apply {
        setWidth(RemoteView.MATCH_PARENT); setHeight(80)
        setImageFileName(imageFileName)
        setScaleType(ScaleType.CENTER_CROP)
    }

    // Rounded image
    val rounded = helper.createImage().apply {
        setWidth(RemoteView.MATCH_PARENT); setHeight(80)
        setImageFileName(imageFileName)
        setScaleType(ScaleType.CENTER_CROP)
        setBackgroundShape(ShapeDescriptor.Builder().cornerRadius(12f).build())
    }

    // Circular image: equal width/height + SHAPE_OVAL
    val circle = helper.createImage().apply {
        setWidth(80); setHeight(80)
        setImageFileName(imageFileName)
        setScaleType(ScaleType.CENTER_CROP)
        setBackgroundShape(
            ShapeDescriptor.Builder()
                .shape(ShapeDescriptor.SHAPE_OVAL)
                .fillColor(Color.RED)
                .build()
        )
    }
}

02 Component Styles (semi-transparent / tint / stroke)

val imageFileName = "sea_view.webp"

// Basic image
val basic = helper.createImage().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(80)
    setImageFileName(imageFileName)
    setScaleType(ScaleType.CENTER_CROP)
    setBackgroundShape(ShapeDescriptor.Builder().cornerRadius(8f).build())
}

// Semi-transparent image: reduced opacity
val semiTransparent = helper.createImage().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(80)
    setImageFileName(imageFileName)
    setScaleType(ScaleType.CENTER_CROP)
    setAlpha(0.4f)
    setBackgroundShape(ShapeDescriptor.Builder().cornerRadius(8f).build())
}

// Tinted image: overlay a 50% transparent yellow mask
val tinted = helper.createImage().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(80)
    setImageFileName(imageFileName)
    setScaleType(ScaleType.CENTER_CROP)
    setImageTint(0x4DFFCC00.toInt())
    setBackgroundShape(ShapeDescriptor.Builder().cornerRadius(8f).build())
}

// Stroked image: 3dp yellow border + rounded corners
val stroked = helper.createImage().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(80)
    setImageFileName(imageFileName)
    setScaleType(ScaleType.CENTER_CROP)
    setBackgroundShape(
        ShapeDescriptor.Builder()
            .cornerRadius(8f)
            .stroke(3, 0xFFFFCC00.toInt())
            .build()
    )
}

For a full runnable example, see drawing/ImageViewDrawer.ktopen in new window in the official Sample open-pilot-plugin-sample.

Last Updated: