Added option to auto-upright requested frame (#35)

Author: cengiz-pz

.github/config/.rubocop.yml

@@ -4,7 +4,7 @@
 
 AllCops:
   TargetRubyVersion: 3.2
-  NewCops: pending
+  NewCops: enable
   Exclude:
     - 'vendor/**/*'
 
@@ -31,9 +31,6 @@ Style/FrozenStringLiteralComment:
 
 Style/Documentation:
   Enabled: false
-
-  AllCops:
-    NewCops: enable
 Gemspec/AddRuntimeDependency: # new in 1.65
   Enabled: true
 Gemspec/AttributeAssignment: # new in 1.77

addon/src/main/NativeCamera.gd

@@ -23,6 +23,7 @@ const PLUGIN_SINGLETON_NAME: String = "@pluginName@"
 @export var frames_to_skip: int = FeedRequest.DEFAULT_FRAMES_TO_SKIP
 
 ## The rotation to be applied to the frame in degrees. Valid values are 0, 90, 180, and 270.
+## Ignored when [member auto_upright] is enabled.
 @export var frame_rotation: int = FeedRequest.DEFAULT_ROTATION
 
 ## Whether the emitted frames should be grayscale or colored.
@@ -44,6 +45,11 @@ const PLUGIN_SINGLETON_NAME: String = "@pluginName@"
 ## non-zero for scaling to take effect.
 @export var scale_height: int = FeedRequest.DEFAULT_SCALE_HEIGHT
 
+## When enabled, each frame is automatically rotated to be upright by combining
+## the camera sensor orientation with the current device orientation.
+## When active, [member frame_rotation] is ignored.
+@export var auto_upright: bool = FeedRequest.DEFAULT_AUTO_UPRIGHT
+
 var _plugin_singleton: Object
 
 
@@ -116,6 +122,7 @@ func create_feed_request() -> FeedRequest:
 		. set_mirror_vertical(mirror_vertical)
 		. set_scale_width(scale_width)
 		. set_scale_height(scale_height)
+		. set_auto_upright(auto_upright)
 	)
 
 

addon/src/main/model/FeedRequest.gd

@@ -14,6 +14,7 @@ const DATA_MIRROR_HORIZONTAL_PROPERTY := &"mirror_horizontal"
 const DATA_MIRROR_VERTICAL_PROPERTY := &"mirror_vertical"
 const DATA_SCALE_WIDTH_PROPERTY := &"scale_width"
 const DATA_SCALE_HEIGHT_PROPERTY := &"scale_height"
+const DATA_AUTO_UPRIGHT_PROPERTY := &"auto_upright"
 
 const DEFAULT_WIDTH: int = 1280
 const DEFAULT_HEIGHT: int = 720
@@ -23,6 +24,10 @@ const DEFAULT_ROTATION: int = 90
 ## Both scale_width and scale_height must be non-zero for scaling to take effect.
 const DEFAULT_SCALE_WIDTH: int = 0
 const DEFAULT_SCALE_HEIGHT: int = 0
+## When true the plugin automatically corrects the frame orientation based on
+## the camera sensor and the live device orientation. The manual [code]rotation[/code]
+## field is ignored while this flag is active.
+const DEFAULT_AUTO_UPRIGHT: bool = false
 
 const DEFAULT_DATA: Dictionary = {
 	DATA_WIDTH_PROPERTY: DEFAULT_WIDTH,
@@ -33,7 +38,8 @@ const DEFAULT_DATA: Dictionary = {
 	DATA_MIRROR_HORIZONTAL_PROPERTY: false,
 	DATA_MIRROR_VERTICAL_PROPERTY: false,
 	DATA_SCALE_WIDTH_PROPERTY: DEFAULT_SCALE_WIDTH,
-	DATA_SCALE_HEIGHT_PROPERTY: DEFAULT_SCALE_HEIGHT
+	DATA_SCALE_HEIGHT_PROPERTY: DEFAULT_SCALE_HEIGHT,
+	DATA_AUTO_UPRIGHT_PROPERTY: DEFAULT_AUTO_UPRIGHT,
 }
 
 var _data: Dictionary
@@ -99,5 +105,14 @@ func set_scale_height(a_value: int) -> FeedRequest:
 	return self
 
 
+## When enabled the plugin automatically computes the rotation required to
+## produce an upright image by combining the camera sensor orientation with the
+## live device orientation. The manual [code]rotation[/code] value is ignored
+## while this flag is active. Defaults to [code]false[/code].
+func set_auto_upright(a_value: bool) -> FeedRequest:
+	_data[DATA_AUTO_UPRIGHT_PROPERTY] = a_value
+	return self
+
+
 func get_raw_data() -> Dictionary:
 	return _data

android/src/main/java/org/godotengine/plugin/nativecamera/NativeCameraPlugin.java

@@ -11,6 +11,7 @@
 import android.graphics.ImageFormat;
 import android.hardware.camera2.CameraAccessException;
 import android.hardware.camera2.CameraCaptureSession;
+import android.hardware.camera2.CameraCharacteristics;
 import android.hardware.camera2.CameraDevice;
 import android.hardware.camera2.CameraManager;
 import android.hardware.camera2.CaptureRequest;
@@ -22,6 +23,8 @@
 import android.os.Handler;
 import android.os.HandlerThread;
 import android.util.Log;
+import android.view.Surface;
+import android.view.WindowManager;
 
 import androidx.core.app.ActivityCompat;
 import androidx.core.content.ContextCompat;
@@ -71,6 +74,29 @@ public class NativeCameraPlugin extends GodotPlugin {
 	private volatile int scaleWidth;
 	/** Target height for post-capture scaling; 0 means disabled. */
 	private volatile int scaleHeight;
+
+	/**
+	 * When true, the rotation applied to each frame is computed automatically
+	 * from the camera sensor orientation and the live device orientation instead
+	 * of using the fixed {@link #rotation} value supplied by the caller.
+	 */
+	private volatile boolean autoUpright;
+
+	/**
+	 * Clockwise angle (0 / 90 / 180 / 270) that the camera sensor image must
+	 * be rotated to be upright when the device is in its natural (portrait)
+	 * orientation.  Populated from {@link CameraCharacteristics#SENSOR_ORIENTATION}
+	 * each time {@link #start} is called.
+	 */
+	private volatile int sensorOrientation;
+
+	/**
+	 * True when the active camera is front-facing.  Used by
+	 * {@link #computeUprightRotation()} to mirror-compensate the rotation
+	 * formula for selfie cameras.
+	 */
+	private volatile boolean isFrontFacingCamera;
+
 	private int frameCounter = 0;
 
 	private volatile boolean running = false;
@@ -174,6 +200,7 @@ public void start(Dictionary requestDict) {
 		mirrorVertical = feedRequest.isMirrorVertical();
 		scaleWidth = feedRequest.getScaleWidth();
 		scaleHeight = feedRequest.getScaleHeight();
+		autoUpright = feedRequest.isAutoUpright();
 		openCamera(feedRequest);
 	}
 
@@ -219,6 +246,21 @@ private void openCamera(FeedRequest request) {
 
 		CameraManager manager = (CameraManager) activity.getSystemService(Context.CAMERA_SERVICE);
 		try {
+			// Read sensor orientation and lens facing so that computeUprightRotation()
+			// has the information it needs without touching the (potentially slow)
+			// CameraCharacteristics API on every frame.
+			CameraCharacteristics characteristics = manager.getCameraCharacteristics(request.getCameraId());
+
+			Integer sensorOrientationValue = characteristics.get(CameraCharacteristics.SENSOR_ORIENTATION);
+			sensorOrientation = (sensorOrientationValue != null) ? sensorOrientationValue : 0;
+
+			Integer lensFacing = characteristics.get(CameraCharacteristics.LENS_FACING);
+			isFrontFacingCamera = (lensFacing != null && lensFacing == CameraCharacteristics.LENS_FACING_FRONT);
+
+			Log.d(LOG_TAG, String.format(
+					"openCamera(): sensorOrientation=%d, isFrontFacing=%b, autoUpright=%b",
+					sensorOrientation, isFrontFacingCamera, autoUpright));
+
 			reader = ImageReader.newInstance(request.getWidth(), request.getHeight(), ImageFormat.YUV_420_888, 2);
 			reader.setOnImageAvailableListener(this::onImageAvailable, bgHandler);
 
@@ -228,6 +270,59 @@ private void openCamera(FeedRequest request) {
 		}
 	}
 
+	/**
+	 * Computes the clockwise rotation (in degrees) required to produce an upright
+	 * image for the currently active camera and the current device orientation.
+	 *
+	 * <p>The algorithm follows the standard Camera2 guidance:
+	 * <ul>
+	 *   <li>Back-facing: {@code (sensorOrientation − deviceDegrees + 360) % 360}</li>
+	 *   <li>Front-facing: {@code (sensorOrientation + deviceDegrees + 360) % 360}<br>
+	 *       The extra compensation accounts for the horizontal mirror inherent to
+	 *       front cameras — the sensor rotation and the device rotation add rather
+	 *       than subtract.</li>
+	 * </ul>
+	 *
+	 * <p>This method is called once per processed frame and is intentionally
+	 * lightweight: the only dynamic read is {@link android.view.Display#getRotation()}.
+	 */
+	private int computeUprightRotation() {
+		Activity activity = getActivity();
+
+		int surfaceRotation;
+		if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+			android.view.Display display = activity.getDisplay();
+			surfaceRotation = (display != null) ? display.getRotation() : Surface.ROTATION_0;
+		} else {
+			WindowManager wm = (WindowManager) activity.getSystemService(Context.WINDOW_SERVICE);
+			//noinspection deprecation
+			surfaceRotation = wm.getDefaultDisplay().getRotation();
+		}
+
+		int deviceDegrees;
+		switch (surfaceRotation) {
+			case Surface.ROTATION_90:  deviceDegrees = 90;  break;
+			case Surface.ROTATION_180: deviceDegrees = 180; break;
+			case Surface.ROTATION_270: deviceDegrees = 270; break;
+			default:                   deviceDegrees = 0;   break;
+		}
+
+		int uprightRotation;
+		if (isFrontFacingCamera) {
+			// Front cameras are horizontally mirrored: sensor and device rotations add.
+			uprightRotation = (sensorOrientation + deviceDegrees + 360) % 360;
+		} else {
+			// Back cameras: sensor rotation minus device rotation.
+			uprightRotation = (sensorOrientation - deviceDegrees + 360) % 360;
+		}
+
+		Log.v(LOG_TAG, String.format(
+				"computeUprightRotation(): deviceDegrees=%d, sensorOrientation=%d, result=%d",
+				deviceDegrees, sensorOrientation, uprightRotation));
+
+		return uprightRotation;
+	}
+
 	void emitFrame(byte[] buffer, int width, int height, int rotation, boolean isGrayscale) {
 		Activity activity = getActivity();
 
@@ -410,12 +505,17 @@ private void onImageAvailable(ImageReader reader) {
 				}
 			}
 
-			if (rotation != 0) {
+			// When auto_upright is enabled, derive the required rotation from the
+			// camera sensor orientation and the live device orientation rather than
+			// using the fixed value set by the caller.
+			int effectiveRotation = autoUpright ? computeUprightRotation() : rotation;
+
+			if (effectiveRotation != 0) {
 				RotationResult result;
 				if (isGrayscale) {
-					result = rotateGray(output, width, height, rotation);
+					result = rotateGray(output, width, height, effectiveRotation);
 				} else {
-					result = rotateRGBA(output, width, height, rotation);
+					result = rotateRGBA(output, width, height, effectiveRotation);
 				}
 
 				output = result.buffer;
@@ -444,7 +544,7 @@ private void onImageAvailable(ImageReader reader) {
 			}
 
 			if (running) {
-				emitFrame(output, width, height, rotation, isGrayscale);
+				emitFrame(output, width, height, effectiveRotation, isGrayscale);
 			}
 
 			image.close();

android/src/main/java/org/godotengine/plugin/nativecamera/model/FeedRequest.java

@@ -21,6 +21,7 @@ public class FeedRequest {
 	private static final String DATA_MIRROR_VERTICAL_PROPERTY = "mirror_vertical";
 	private static final String DATA_SCALE_WIDTH_PROPERTY = "scale_width";
 	private static final String DATA_SCALE_HEIGHT_PROPERTY = "scale_height";
+	private static final String DATA_AUTO_UPRIGHT_PROPERTY = "auto_upright";
 
 	private Dictionary data;
 
@@ -92,6 +93,18 @@ public int getScaleHeight() {
 	}
 
 
+	/**
+	 * When true the plugin will automatically compute the rotation needed to
+	 * produce an upright image, taking into account both the camera sensor
+	 * orientation and the current device orientation.  The manual {@code rotation}
+	 * field is ignored while this flag is active.
+	 */
+	public boolean isAutoUpright() {
+		return data.containsKey(DATA_AUTO_UPRIGHT_PROPERTY) ?
+				(boolean) data.get(DATA_AUTO_UPRIGHT_PROPERTY) : false;
+	}
+
+
 	public Dictionary getRawData() {
 		return data;
 	}

android/src/test/java/org/godotengine/plugin/nativecamera/CameraInfoTest.java

@@ -31,7 +31,7 @@
 @ExtendWith(MockitoExtension.class)
 public class CameraInfoTest {
 
-	// ── helpers ───────────────────────────────────────────────────────────
+	// -- helpers -----------------------------------------------------------
 
 	private static Size size(int w, int h) {
 		Size s = mock(Size.class);
@@ -81,7 +81,7 @@ private CameraCharacteristics mockCharacteristicsNullFacing(Size[] outputSizes)
 		return chars;
 	}
 
-	// ── camera_id ─────────────────────────────────────────────────────────
+	// -- camera_id ---------------------------------------------------------
 
 	@Test
 	public void buildRawData_cameraIdBackCamera() {
@@ -97,7 +97,7 @@ public void buildRawData_cameraIdFrontCamera() {
 		assertEquals("1", info.buildRawData().get("camera_id"));
 	}
 
-	// ── is_front_facing ───────────────────────────────────────────────────
+	// -- is_front_facing ---------------------------------------------------
 
 	@Test
 	public void buildRawData_backCamera_isFrontFacingFalse() {
@@ -120,7 +120,7 @@ public void buildRawData_nullFacing_isFrontFacingFalse() {
 		assertFalse((Boolean) info.buildRawData().get("is_front_facing"));
 	}
 
-	// ── output_sizes ──────────────────────────────────────────────────────
+	// -- output_sizes ------------------------------------------------------
 
 	@Test
 	public void buildRawData_noOutputSizes_returnsEmptyArray() {
@@ -169,7 +169,7 @@ public void buildRawData_nullOutputSizesArray_returnsEmptyArray() {
 		assertEquals(0, result.length);
 	}
 
-	// ── key completeness ─────────────────────────────────────────────────
+	// -- key completeness -------------------------------------------------
 
 	@Test
 	public void buildRawData_containsAllExpectedKeys() {

android/src/test/java/org/godotengine/plugin/nativecamera/FeedRequestTest.java

@@ -318,6 +318,67 @@ public void scaleHeightOnlyDict_widthRemainsZero() {
 		assertEquals(360, req.getScaleHeight());
 	}
 
+	// ── autoUpright ───────────────────────────────────────────────────────
+
+	@Test
+	public void isAutoUpright_falseInFullDict() {
+		// fullDict() explicitly sets auto_upright = false
+		FeedRequest req = new FeedRequest(FeedRequestFixtures.fullDict());
+		assertFalse(req.isAutoUpright());
+	}
+
+	@Test
+	public void isAutoUpright_trueInAutoUprightDict() {
+		FeedRequest req = new FeedRequest(FeedRequestFixtures.autoUprightDict());
+		assertTrue(req.isAutoUpright());
+	}
+
+	@Test
+	public void isAutoUpright_missingKey_defaultsFalse() {
+		// Missing key must default to false — auto_upright is opt-in.
+		FeedRequest req = new FeedRequest(FeedRequestFixtures.emptyDict());
+		assertFalse(req.isAutoUpright());
+	}
+
+	@Test
+	public void isAutoUpright_minimalDict_defaultsFalse() {
+		FeedRequest req = new FeedRequest(FeedRequestFixtures.minimalDict());
+		assertFalse(req.isAutoUpright());
+	}
+
+	@Test
+	public void isAutoUpright_frontCameraAutoUprightDict_trueAndCorrectCameraId() {
+		// Verify that auto_upright and camera_id are independent fields.
+		FeedRequest req = new FeedRequest(FeedRequestFixtures.frontCameraAutoUprightDict());
+		assertTrue(req.isAutoUpright());
+		assertEquals("1", req.getCameraId());
+	}
+
+	@Test
+	public void isAutoUpright_explicitFalseInDict_returnsFalse() {
+		// Explicit false must not be treated as missing.
+		Dictionary d = new Dictionary();
+		d.put("auto_upright", false);
+		FeedRequest req = new FeedRequest(d);
+		assertFalse(req.isAutoUpright());
+	}
+
+	@Test
+	public void isAutoUpright_explicitTrueInDict_returnsTrue() {
+		Dictionary d = new Dictionary();
+		d.put("auto_upright", true);
+		FeedRequest req = new FeedRequest(d);
+		assertTrue(req.isAutoUpright());
+	}
+
+	@Test
+	public void isAutoUpright_doesNotAffectRotationGetter() {
+		// Enabling auto_upright must leave the stored rotation value untouched;
+		// the plugin (not FeedRequest) decides which rotation to apply at runtime.
+		FeedRequest req = new FeedRequest(FeedRequestFixtures.autoUprightDict());
+		assertEquals(90, req.getRotation()); // fullDict rotation is 90
+	}
+
 	// ── type coercion (Long -> int) ───────────────────────────────────────
 
 	@Test