feat: Add a capability to adjust injected image properties (#942)

Author: mykola-mokhnach

Diff for: lib/commands/device/utils.js

@@ -9,6 +9,7 @@ import {
   EMPTY_IME,
 } from 'io.appium.settings';
 import B from 'bluebird';
+import { prepareEmulatorForImageInjection } from '../image-injection';
 
 const HELPER_APP_INSTALL_RETRIES = 3;
 const HELPER_APP_INSTALL_RETRY_DELAY_MS = 5000;
@@ -118,8 +119,9 @@ export async function prepareEmulator(adb) {
   }
   const args = prepareAvdArgs.bind(this)();
   if (isEmulatorRunning) {
-    if (args.includes('-wipe-data')) {
-      this.log.debug(`Killing '${avdName}' because it needs to be wiped at start.`);
+    if (await prepareEmulatorForImageInjection.bind(this)(/** @type {string} */ (adb.sdkRoot))
+      || args.includes('-wipe-data')) {
+      this.log.debug(`Killing '${avdName}'`);
       await adb.killEmulator(avdName);
     } else {
       this.log.debug('Not launching AVD because it is already running.');

Diff for: lib/commands/image-injection.js

@@ -6,25 +6,73 @@ import _ from 'lodash';
 
 const EMULATOR_RESOURCES_ROOT = ['emulator', 'resources'];
 const CONFIG_NAME = 'Toren1BD.posters';
-const CONFIG = `poster wall
+const DEFAULT_CONFIG_PAYLOAD_PREFIX = `poster wall
 size 2 2
 position -0.807 0.320 5.316
 rotation 0 -150 0
 default poster.png
 
-poster table
+poster table`;
+const DEFAULT_CONFIG_PAYLOAD = `${DEFAULT_CONFIG_PAYLOAD_PREFIX}
 size 1 1
 position 0 0 -1.5
 rotation 0 0 0
 `;
 const PNG_MAGIC = '89504e47';
 const PNG_MAGIC_LENGTH = 4;
 
+/**
+ * Updates the emulator configuration to show the
+ * image using the given properties when one opens the Camera app.
+ *
+ * @this {AndroidDriver}
+ * @param {string} sdkRoot ADB SDK root folder path
+ * @returns {Promise<boolean>} If emulator services restart is needed
+ * to load the updated config or false if the current config is already up to date
+ * or does not need to be updated
+ */
+export async function prepareEmulatorForImageInjection(sdkRoot) {
+  const { injectedImageProperties: props } = this.opts;
+  if (!props) {
+    return false;
+  }
+
+  const size = `size ${props.size?.scaleX ?? 1} ${props.size?.scaleY ?? 1}`;
+  const position = `position ${props.position?.x ?? 0} ${props.position?.y ?? 0} ${props.position?.z ?? -1.5}`;
+  const rotation = `rotation ${props.rotation?.x ?? 0} ${props.rotation?.y ?? 0} ${props.rotation?.z ?? 0}`;
+  const strProps = `${size}\n${position}\n${rotation}`;
+  const configPath = path.resolve(sdkRoot, ...EMULATOR_RESOURCES_ROOT, CONFIG_NAME);
+  if (await fs.exists(configPath)) {
+    const configPayload = await fs.readFile(configPath, 'utf8');
+    if (configPayload.includes(strProps)) {
+      this.log.info(`The image injection config at '${configPath}' is already up to date. Doing nothing`);
+      return false;
+    }
+    const updatedPayload = `${DEFAULT_CONFIG_PAYLOAD_PREFIX}
+    ${size}
+    ${position}
+    ${rotation}
+    `;
+    await fs.writeFile(configPath, updatedPayload, 'utf-8');
+  } else {
+    await fs.writeFile(configPath, DEFAULT_CONFIG_PAYLOAD, 'utf-8');
+  }
+  this.log.info(
+    `The image injection config at '${configPath}' has been successfully updated with ` +
+    `${size}, ${position}, ${rotation}. ` +
+    `Expecting further emulator restart to reload the changed config.`
+  );
+  return true;
+}
+
 /**
  * Updates the emulator configuration to show the given
  * image on the foreground when one opens the Camera app.
  * It is expected that the rear camera of the emulator is
  * configured to show VirtualScene for this feature to work.
+ * It is expected that the Virtual Scene posters config is
+ * already prepared and loaded either manually or using the
+ * `injectedImageProperties` capability.
  *
  * @this {AndroidDriver}
  * @param {import('./types').ImageInjectionOpts} opts
@@ -49,9 +97,6 @@ export async function mobileInjectEmulatorCameraImage(opts) {
     );
   }
 
-  const sdkRoot = /** @type {string} */ (this.adb.sdkRoot);
-  const destinationFolder = path.resolve(sdkRoot, ...EMULATOR_RESOURCES_ROOT);
-  await fs.writeFile(path.resolve(destinationFolder, CONFIG_NAME), CONFIG, 'utf-8');
   const tmpImagePath = await tempDir.path({
     // this is needed to avoid creation of multiple temp files for the same image payload
     prefix: calculateImageHash(pngBuffer),

Diff for: lib/commands/types.ts

@@ -1233,3 +1233,34 @@ export interface BluetoothOptions {
 export interface NfcOptions {
   action: 'enable' | 'disable';
 }
+
+export interface InjectedImageSize {
+  /** X scale value in range (0..) */
+  scaleX?: number;
+  /** Y scale value in range (0..) */
+  scaleY?: number;
+}
+
+export interface InjectedImagePosition {
+  /** Normalized X coordinate, where 0 means the image is centered on the viewport */
+  x?: number;
+  /** Normalized Y coordinate, where 0 means the image is centered on the viewport */
+  y?: number;
+  /** Normalized Z coordinate, where 0 means the image is centered on the viewport */
+  z?: number;
+}
+
+export interface InjectedImageRotation {
+  /** X rotation value in degrees */
+  x?: number;
+  /** Y rotation value in degrees */
+  y?: number;
+  /** Z rotation value in degrees */
+  z?: number;
+}
+
+export interface InjectedImageProperties {
+  size?: InjectedImageSize;
+  position?: InjectedImagePosition;
+  rotation?: InjectedImageRotation;
+}

Diff for: lib/constraints.ts

@@ -266,6 +266,9 @@ export const ANDROID_DRIVER_CONSTRAINTS = {
   timeZone: {
     isString: true,
   },
+  injectedImageProperties: {
+    isObject: true,
+  }
 } as const satisfies Constraints;
 
 export default ANDROID_DRIVER_CONSTRAINTS;