@rayabelcode/expo-image-orientation-normalizer 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ray Abel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# @rayabelcode/expo-image-orientation-normalizer
+
+[![npm version](https://img.shields.io/npm/v/@rayabelcode/expo-image-orientation-normalizer.svg)](https://www.npmjs.com/package/@rayabelcode/expo-image-orientation-normalizer)
+[![license](https://img.shields.io/npm/l/@rayabelcode/expo-image-orientation-normalizer.svg)](./LICENSE)
+
+Native ingress normalization for gallery-picked images on React Native (Expo).
+
+Decodes the source image through the platform's native frameworks (PhotoKit + ImageIO on iOS, BitmapFactory + ExifInterface + Matrix on Android), applies orientation to pixels, and writes a fresh JPEG with `EXIF Orientation = 1`. Downstream consumers — image manipulation libraries, crop UIs, upload services — see consistent display-oriented pixels without having to read or branch on EXIF.
+
+## Why this exists
+
+iOS HEIC and EXIF-tagged JPEGs from gallery pickers don't reach your downstream pipeline with consistent pixel orientation. The picker returns a `file://` URI to a file whose stored pixels may be in sensor orientation while the EXIF Orientation tag instructs "rotate for display." Various downstream tools (image processors, crop UIs, upload code) handle this inconsistently — and the inconsistency is per-file, not per-app. The result: some uploads end up sideways while others don't.
+
+JS-layer heuristics can't fix this reliably because EXIF tags and stored dimensions can disagree per-file. This module bypasses the issue by normalizing at the native ingress boundary: the gallery picker hands you a URI, you pass it to `normalizePickedImage`, and the result is a JPEG with display-oriented pixels and `Orientation = 1`. Everything downstream stops caring about EXIF.
+
+## Installation
+
+```bash
+npm install @rayabelcode/expo-image-orientation-normalizer
+cd ios && pod install
+```
+
+Requires:
+
+- Expo SDK 50 or newer
+- React Native 0.73 or newer
+- iOS 16.4+ deployment target
+- Android `minSdkVersion` 24+
+
+## Quick start
+
+```ts
+import * as ImagePicker from 'expo-image-picker';
+import { normalizePickedImage } from '@rayabelcode/expo-image-orientation-normalizer';
+
+const result = await ImagePicker.launchImageLibraryAsync({
+  mediaTypes: ['images'],
+  quality: 1.0,
+  exif: true,
+});
+if (result.canceled || !result.assets[0]) return;
+const asset = result.assets[0];
+
+const normalized = await normalizePickedImage({
+  uri: asset.uri,
+  assetId: asset.assetId ?? undefined, // enables the PhotoKit path on iOS
+  mimeType: asset.mimeType ?? undefined,
+  maxLongEdge: 2000,
+  quality: 0.9,
+});
+
+// normalized.uri    →  file:// to a fresh JPEG with display-oriented pixels + Orientation=1
+// normalized.width  →  post-rotation pixel width
+// normalized.height →  post-rotation pixel height
+// normalized.source →  which native path ran (see below)
+```
+
+## API
+
+```ts
+function normalizePickedImage(options: NormalizePickedImageOptions): Promise<NormalizedImage>;
+
+interface NormalizePickedImageOptions {
+  uri: string; // file:// URI from the picker (or content:// on Android)
+  assetId?: string; // PHAsset localIdentifier — enables PhotoKit on iOS
+  mimeType?: string; // best-effort hint
+  maxLongEdge: number; // long-edge cap (Android downsamples at decode for OOM safety)
+  quality: number; // 0..1 JPEG quality
+}
+
+interface NormalizedImage {
+  uri: string; // file:// to the output JPEG (app cache directory)
+  width: number; // post-rotation pixel width
+  height: number; // post-rotation pixel height
+  orientation: 1; // always 1
+  source: NormalizationSource;
+}
+
+type NormalizationSource = 'photo-asset' | 'imageio' | 'exifinterface' | 'fallback';
+```
+
+## Native paths
+
+| `source`        | When                                                                                                                                                                                   | Stale-EXIF-resistant?                                                       |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `photo-asset`   | iOS, `assetId` provided — PhotoKit `PHImageManager.requestImage` renders the photo-library canonical image, then `UIGraphicsImageRenderer.draw` bakes orientation to a `.up` `CGImage` | **Yes** — renders what the user sees in Photos.app, regardless of file EXIF |
+| `imageio`       | iOS fallback when `assetId` is absent or PhotoKit fails — `CGImageSourceCreateThumbnailAtIndex` with `kCGImageSourceCreateThumbnailWithTransform: true`                                | No — metadata-faithful; trusts the file's EXIF tag                          |
+| `exifinterface` | Android — `BitmapFactory` (sample-size pre-decode), `androidx.exifinterface.media.ExifInterface` reads the tag, `Matrix.postRotate` / `postScale` applies all 8 EXIF values            | No — metadata-faithful; trusts the file's EXIF tag                          |
+
+## Contract
+
+- **Always writes a new file.** Never returns the input URI.
+- **Output is JPEG** with EXIF Orientation = 1 (or absent).
+- **Throws on hard failure.** Callers MUST surface the error and cancel — never proceed with the un-normalized input URI.
+- **`maxLongEdge` must be > 0**; `quality` is clamped to `[0, 1]`.
+- **Off main thread.** Decode/encode runs on a background queue via Expo Modules' `AsyncFunction`.
+- **URI schemes accepted**: `file://`, raw filesystem paths, and `content://` (Android only — copied to app cache first).
+
+## Known limitations — stale EXIF
+
+The `imageio` and `exifinterface` paths trust the file's EXIF Orientation tag. They cannot detect a **stale** tag — where pixels are already display-oriented but the EXIF tag still says "rotate." Stale-EXIF inputs will come out over-rotated on these paths.
+
+- **iOS without an `assetId`** (raw file URI only): metadata-faithful only.
+- **Android**: metadata-faithful only — no equivalent of PhotoKit's display-source render.
+
+If stale EXIF is common in your image corpus, options are (a) add Coil or Glide on Android for a display-source render path, or (b) add a user-facing rotate button as an explicit override.
+
+## Permissions
+
+PhotoKit (iOS) requires `NSPhotoLibraryUsageDescription` in `Info.plist`. With Expo, add to `app.json`:
+
+```json
+{
+  "expo": {
+    "ios": {
+      "infoPlist": {
+        "NSPhotoLibraryUsageDescription": "We need access to your photo library to import images."
+      }
+    }
+  }
+}
+```
+
+Android does not require additional permissions beyond what `expo-image-picker` (or your picker of choice) already declares.
+
+## Native frameworks used
+
+**iOS**: `Photos` (PHAsset, PHImageManager), `ImageIO` (CGImageSource, CGImageDestination), `UIKit` (UIGraphicsImageRenderer), `UniformTypeIdentifiers` (UTType.jpeg). Deployment target iOS 16.4+.
+
+**Android**: `android.graphics.BitmapFactory`, `Bitmap`, `Matrix`; `androidx.exifinterface.media.ExifInterface` (1.4.x).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/android/build.gradle

@@ -0,0 +1,22 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'expo.modules.imageorientationnormalizer'
+version = '0.9.0'
+
+android {
+  namespace "expo.modules.imageorientationnormalizer"
+  defaultConfig {
+    versionCode 1
+    versionName "0.9.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+}
+
+dependencies {
+  implementation "androidx.exifinterface:exifinterface:1.4.2"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest>
+</manifest>

package/android/src/main/java/expo/modules/imageorientationnormalizer/ImageOrientationNormalizerModule.kt

@@ -0,0 +1,187 @@
+package expo.modules.imageorientationnormalizer
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Matrix
+import android.net.Uri
+import androidx.exifinterface.media.ExifInterface
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+import java.io.File
+import java.io.FileOutputStream
+import java.util.UUID
+
+class ImageOrientationNormalizerModule : Module() {
+	override fun definition() = ModuleDefinition {
+		Name("ImageOrientationNormalizer")
+
+		AsyncFunction("normalizePickedImage") { options: NormalizePickedImageOptions ->
+			normalize(options)
+		}
+	}
+
+	private fun normalize(options: NormalizePickedImageOptions): NormalizedImage {
+		validate(options)
+		val quality = clampedQuality(options.quality)
+		val maxLongEdge = options.maxLongEdge.toInt()
+
+		val inputPath = resolveLocalPath(options.uri)
+		val inputFile = File(inputPath)
+		if (!inputFile.exists()) {
+			throw NormalizationError("Input file does not exist: $inputPath")
+		}
+
+		// 1. Source dims (no pixel allocation).
+		val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+		BitmapFactory.decodeFile(inputPath, bounds)
+		if (bounds.outWidth <= 0 || bounds.outHeight <= 0) {
+			throw NormalizationError("Cannot decode source: $inputPath")
+		}
+
+		// 2. Sample-size pre-decode for OOM safety on large sources.
+		val sampleSize = computeSampleSize(bounds.outWidth, bounds.outHeight, maxLongEdge)
+		val decodeOpts = BitmapFactory.Options().apply {
+			inSampleSize = sampleSize
+			inPreferredConfig = Bitmap.Config.ARGB_8888
+		}
+		val raw = BitmapFactory.decodeFile(inputPath, decodeOpts)
+			?: throw NormalizationError("Decode returned null: $inputPath")
+
+		// 3. Apply EXIF orientation. Metadata-faithful — trusts the tag.
+		val orientation = readExifOrientation(inputPath)
+		val oriented = applyOrientation(raw, orientation)
+		if (oriented !== raw) raw.recycle()
+
+		// 4. Long-edge scale.
+		val finalBitmap = applyMaxLongEdge(oriented, maxLongEdge)
+		if (finalBitmap !== oriented) oriented.recycle()
+
+		// 5. Write JPEG to app cache.
+		val cacheDir = appContext.reactContext?.cacheDir
+			?: throw NormalizationError("No reactContext.cacheDir available")
+		val outFile = File(cacheDir, "normalized_${UUID.randomUUID()}.jpg")
+		FileOutputStream(outFile).use { os ->
+			val ok = finalBitmap.compress(Bitmap.CompressFormat.JPEG, (quality * 100).toInt(), os)
+			if (!ok) throw NormalizationError("Failed to encode JPEG: ${outFile.absolutePath}")
+		}
+
+		// 6. Clear EXIF orientation on output.
+		ExifInterface(outFile.absolutePath).apply {
+			resetOrientation()
+			saveAttributes()
+		}
+
+		val width = finalBitmap.width
+		val height = finalBitmap.height
+		finalBitmap.recycle()
+
+		return NormalizedImage().apply {
+			uri = "file://${outFile.absolutePath}"
+			this.width = width.toDouble()
+			this.height = height.toDouble()
+			this.orientation = 1
+			source = "exifinterface"
+		}
+	}
+
+	private fun resolveLocalPath(uri: String): String {
+		if (uri.startsWith("file://")) return Uri.parse(uri).path
+			?: throw NormalizationError("Cannot resolve file URI: $uri")
+		if (uri.startsWith("/")) return uri
+		if (uri.startsWith("content://")) return copyContentToTemp(Uri.parse(uri))
+		throw NormalizationError("Unsupported URI scheme: $uri")
+	}
+
+	private fun copyContentToTemp(uri: Uri): String {
+		val resolver = appContext.reactContext?.contentResolver
+			?: throw NormalizationError("No contentResolver available")
+		val cacheDir = appContext.reactContext?.cacheDir
+			?: throw NormalizationError("No reactContext.cacheDir available")
+		val temp = File(cacheDir, "picker_${UUID.randomUUID()}.bin")
+		resolver.openInputStream(uri).use { input ->
+			if (input == null) throw NormalizationError("Cannot open content URI: $uri")
+			FileOutputStream(temp).use { output -> input.copyTo(output) }
+		}
+		return temp.absolutePath
+	}
+
+	private fun readExifOrientation(path: String): Int {
+		return try {
+			ExifInterface(path).getAttributeInt(
+				ExifInterface.TAG_ORIENTATION,
+				ExifInterface.ORIENTATION_NORMAL,
+			)
+		} catch (e: Throwable) {
+			ExifInterface.ORIENTATION_NORMAL
+		}
+	}
+
+	private fun applyOrientation(src: Bitmap, orientation: Int): Bitmap {
+		val matrix = Matrix()
+		when (orientation) {
+			ExifInterface.ORIENTATION_ROTATE_90 -> matrix.postRotate(90f)
+			ExifInterface.ORIENTATION_ROTATE_180 -> matrix.postRotate(180f)
+			ExifInterface.ORIENTATION_ROTATE_270 -> matrix.postRotate(270f)
+			ExifInterface.ORIENTATION_FLIP_HORIZONTAL -> matrix.postScale(-1f, 1f)
+			ExifInterface.ORIENTATION_FLIP_VERTICAL -> matrix.postScale(1f, -1f)
+			ExifInterface.ORIENTATION_TRANSPOSE -> {
+				matrix.postRotate(90f)
+				matrix.postScale(-1f, 1f)
+			}
+			ExifInterface.ORIENTATION_TRANSVERSE -> {
+				matrix.postRotate(-90f)
+				matrix.postScale(-1f, 1f)
+			}
+			else -> return src
+		}
+		return Bitmap.createBitmap(src, 0, 0, src.width, src.height, matrix, true)
+	}
+
+	private fun computeSampleSize(width: Int, height: Int, maxLongEdge: Int): Int {
+		// Decode at the smallest sample size where the larger edge is still ≥ 2x maxLongEdge,
+		// leaving the final long-edge resize a clean pass over high-quality pixels.
+		val longestEdge = maxOf(width, height)
+		var sample = 1
+		while (longestEdge / sample > maxLongEdge * 2) {
+			sample *= 2
+		}
+		return sample
+	}
+
+	private fun applyMaxLongEdge(src: Bitmap, maxLongEdge: Int): Bitmap {
+		val longest = maxOf(src.width, src.height)
+		if (longest <= maxLongEdge) return src
+		val scale = maxLongEdge.toDouble() / longest.toDouble()
+		val targetW = (src.width * scale).toInt().coerceAtLeast(1)
+		val targetH = (src.height * scale).toInt().coerceAtLeast(1)
+		return Bitmap.createScaledBitmap(src, targetW, targetH, true)
+	}
+
+	private fun validate(options: NormalizePickedImageOptions) {
+		if (options.uri.isEmpty()) throw NormalizationError("uri is required")
+		if (options.maxLongEdge <= 0.0) throw NormalizationError("maxLongEdge must be > 0")
+	}
+
+	private fun clampedQuality(q: Double): Double = q.coerceIn(0.0, 1.0)
+}
+
+class NormalizePickedImageOptions : Record {
+	@Field var uri: String = ""
+	@Field var assetId: String? = null
+	@Field var mimeType: String? = null
+	@Field var maxLongEdge: Double = 2000.0
+	@Field var quality: Double = 0.9
+}
+
+class NormalizedImage : Record {
+	@Field var uri: String = ""
+	@Field var width: Double = 0.0
+	@Field var height: Double = 0.0
+	@Field var orientation: Int = 1
+	@Field var source: String = "fallback"
+}
+
+class NormalizationError(message: String) : CodedException(message)

package/build/ImageOrientationNormalizer.types.d.ts

@@ -0,0 +1,16 @@
+export type NormalizationSource = 'photo-asset' | 'imageio' | 'exifinterface' | 'fallback';
+export interface NormalizedImage {
+    uri: string;
+    width: number;
+    height: number;
+    orientation: 1;
+    source: NormalizationSource;
+}
+export interface NormalizePickedImageOptions {
+    uri: string;
+    assetId?: string;
+    mimeType?: string;
+    maxLongEdge: number;
+    quality: number;
+}
+//# sourceMappingURL=ImageOrientationNormalizer.types.d.ts.map

package/build/ImageOrientationNormalizer.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageOrientationNormalizer.types.d.ts","sourceRoot":"","sources":["../src/ImageOrientationNormalizer.types.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,SAAS,GAAG,eAAe,GAAG,UAAU,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,CAAC,CAAC;IACf,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,WAAW,2BAA2B;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/build/ImageOrientationNormalizer.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ImageOrientationNormalizer.types.js.map

package/build/ImageOrientationNormalizer.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageOrientationNormalizer.types.js","sourceRoot":"","sources":["../src/ImageOrientationNormalizer.types.ts"],"names":[],"mappings":"","sourcesContent":["// Which native render path produced the output. `photo-asset` is display-source\n// (stale-EXIF-resistant via PhotoKit); `imageio` and `exifinterface` are\n// metadata-faithful — they trust the file's EXIF tag and cannot detect a lying\n// tag. `fallback` indicates the stub returned the input URI unchanged.\nexport type NormalizationSource = 'photo-asset' | 'imageio' | 'exifinterface' | 'fallback';\n\nexport interface NormalizedImage {\n  uri: string;\n  width: number;\n  height: number;\n  orientation: 1;\n  source: NormalizationSource;\n}\n\nexport interface NormalizePickedImageOptions {\n  uri: string;\n  assetId?: string;\n  mimeType?: string;\n  maxLongEdge: number;\n  quality: number;\n}\n"]}

package/build/ImageOrientationNormalizerModule.d.ts

@@ -0,0 +1,8 @@
+import { NativeModule } from 'expo';
+import type { NormalizePickedImageOptions, NormalizedImage } from './ImageOrientationNormalizer.types';
+declare class ImageOrientationNormalizerModule extends NativeModule<Record<string, never>> {
+    normalizePickedImage(options: NormalizePickedImageOptions): Promise<NormalizedImage>;
+}
+declare const _default: ImageOrientationNormalizerModule;
+export default _default;
+//# sourceMappingURL=ImageOrientationNormalizerModule.d.ts.map

package/build/ImageOrientationNormalizerModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageOrientationNormalizerModule.d.ts","sourceRoot":"","sources":["../src/ImageOrientationNormalizerModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,MAAM,CAAC;AAEzD,OAAO,KAAK,EACV,2BAA2B,EAC3B,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,OAAO,gCAAiC,SAAQ,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACxF,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,eAAe,CAAC;CACrF;;AAED,wBAAmG"}

package/build/ImageOrientationNormalizerModule.js

@@ -0,0 +1,3 @@
+import { requireNativeModule } from 'expo';
+export default requireNativeModule('ImageOrientationNormalizer');
+//# sourceMappingURL=ImageOrientationNormalizerModule.js.map

package/build/ImageOrientationNormalizerModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageOrientationNormalizerModule.js","sourceRoot":"","sources":["../src/ImageOrientationNormalizerModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,mBAAmB,EAAE,MAAM,MAAM,CAAC;AAWzD,eAAe,mBAAmB,CAAmC,4BAA4B,CAAC,CAAC","sourcesContent":["import { NativeModule, requireNativeModule } from 'expo';\n\nimport type {\n  NormalizePickedImageOptions,\n  NormalizedImage,\n} from './ImageOrientationNormalizer.types';\n\ndeclare class ImageOrientationNormalizerModule extends NativeModule<Record<string, never>> {\n  normalizePickedImage(options: NormalizePickedImageOptions): Promise<NormalizedImage>;\n}\n\nexport default requireNativeModule<ImageOrientationNormalizerModule>('ImageOrientationNormalizer');\n"]}

package/build/index.d.ts

@@ -0,0 +1,4 @@
+import type { NormalizePickedImageOptions, NormalizedImage, NormalizationSource } from './ImageOrientationNormalizer.types';
+export type { NormalizePickedImageOptions, NormalizedImage, NormalizationSource };
+export declare function normalizePickedImage(options: NormalizePickedImageOptions): Promise<NormalizedImage>;
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,2BAA2B,EAC3B,eAAe,EACf,mBAAmB,EACpB,MAAM,oCAAoC,CAAC;AAG5C,YAAY,EAAE,2BAA2B,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC;AAElF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,CAE1B"}

package/build/index.js

@@ -0,0 +1,15 @@
+// Public entry point for the ImageOrientationNormalizer module.
+//
+// Normalizes a gallery-picked image to a fresh JPEG with display-oriented
+// pixels and EXIF Orientation=1. Throws on hard failure — callers MUST surface
+// the error and cancel; never proceed with the un-normalized input URI.
+//
+// Only the `photo-asset` source (PhotoKit on iOS when an assetId is provided)
+// is stale-EXIF-resistant. The `imageio` and `exifinterface` paths are
+// metadata-faithful — they trust the file's EXIF tag and cannot detect a
+// lying tag.
+import ImageOrientationNormalizerModule from './ImageOrientationNormalizerModule';
+export function normalizePickedImage(options) {
+    return ImageOrientationNormalizerModule.normalizePickedImage(options);
+}
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,wEAAwE;AACxE,EAAE;AACF,8EAA8E;AAC9E,uEAAuE;AACvE,yEAAyE;AACzE,aAAa;AAOb,OAAO,gCAAgC,MAAM,oCAAoC,CAAC;AAIlF,MAAM,UAAU,oBAAoB,CAClC,OAAoC;IAEpC,OAAO,gCAAgC,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;AACxE,CAAC","sourcesContent":["// Public entry point for the ImageOrientationNormalizer module.\n//\n// Normalizes a gallery-picked image to a fresh JPEG with display-oriented\n// pixels and EXIF Orientation=1. Throws on hard failure — callers MUST surface\n// the error and cancel; never proceed with the un-normalized input URI.\n//\n// Only the `photo-asset` source (PhotoKit on iOS when an assetId is provided)\n// is stale-EXIF-resistant. The `imageio` and `exifinterface` paths are\n// metadata-faithful — they trust the file's EXIF tag and cannot detect a\n// lying tag.\n\nimport type {\n  NormalizePickedImageOptions,\n  NormalizedImage,\n  NormalizationSource,\n} from './ImageOrientationNormalizer.types';\nimport ImageOrientationNormalizerModule from './ImageOrientationNormalizerModule';\n\nexport type { NormalizePickedImageOptions, NormalizedImage, NormalizationSource };\n\nexport function normalizePickedImage(\n  options: NormalizePickedImageOptions\n): Promise<NormalizedImage> {\n  return ImageOrientationNormalizerModule.normalizePickedImage(options);\n}\n"]}

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["apple", "android"],
+  "apple": {
+    "modules": ["ImageOrientationNormalizerModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.imageorientationnormalizer.ImageOrientationNormalizerModule"]
+  }
+}

package/ios/ImageOrientationNormalizer.podspec

@@ -0,0 +1,23 @@
+Pod::Spec.new do |s|
+  s.name           = 'ImageOrientationNormalizer'
+  s.version        = '0.9.0'
+  s.summary        = 'Native ingress normalization for gallery-picked images on React Native / Expo.'
+  s.description    = 'Decodes via PhotoKit and ImageIO on iOS, BitmapFactory + ExifInterface + Matrix on Android; writes display-oriented JPEG with EXIF Orientation=1.'
+  s.author         = 'Ray Abel'
+  s.homepage       = 'https://github.com/rayabelcode/expo-image-orientation-normalizer'
+  s.license        = { type: 'MIT', file: '../LICENSE' }
+  s.platforms      = {
+    :ios => '16.4',
+    :tvos => '16.4'
+  }
+  s.source         = { git: 'https://github.com/rayabelcode/expo-image-orientation-normalizer.git', tag: s.version.to_s }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+  }
+
+  s.source_files = "**/*.{h,m,mm,swift,hpp,cpp}"
+end

package/ios/ImageOrientationNormalizerModule.swift

@@ -0,0 +1,201 @@
+import ExpoModulesCore
+import ImageIO
+import Photos
+import UIKit
+import UniformTypeIdentifiers
+
+public class ImageOrientationNormalizerModule: Module {
+	public func definition() -> ModuleDefinition {
+		Name("ImageOrientationNormalizer")
+
+		AsyncFunction("normalizePickedImage") { (options: NormalizePickedImageOptions) -> NormalizedImage in
+			return try self.normalize(options)
+		}
+	}
+
+	private func normalize(_ options: NormalizePickedImageOptions) throws -> NormalizedImage {
+		try validate(options)
+		let quality = clampedQuality(options.quality)
+		let maxLongEdge = options.maxLongEdge
+
+		if let assetId = options.assetId, !assetId.isEmpty {
+			if let result = try? renderViaPhotoKit(assetId: assetId, maxLongEdge: maxLongEdge, quality: quality) {
+				return result
+			}
+			// PhotoKit miss (asset not found, permission denied, network unavailable) → fall through.
+		}
+
+		return try renderViaImageIO(uri: options.uri, maxLongEdge: maxLongEdge, quality: quality)
+	}
+
+	// MARK: - ImageIO path (metadata-faithful)
+
+	private func renderViaImageIO(uri: String, maxLongEdge: Double, quality: Double) throws -> NormalizedImage {
+		guard let url = parseURL(uri) else {
+			throw NormalizationError.invalidUri(uri)
+		}
+		guard let source = CGImageSourceCreateWithURL(url as CFURL, nil) else {
+			throw NormalizationError.cannotOpen(uri)
+		}
+
+		// kCGImageSourceCreateThumbnailWithTransform: true applies EXIF during decode.
+		// Metadata-faithful — does NOT detect stale tags.
+		let opts: [CFString: Any] = [
+			kCGImageSourceCreateThumbnailFromImageAlways: true,
+			kCGImageSourceCreateThumbnailWithTransform: true,
+			kCGImageSourceThumbnailMaxPixelSize: NSNumber(value: maxLongEdge),
+		]
+		guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, opts as CFDictionary) else {
+			throw NormalizationError.decodeFailed
+		}
+
+		return try writeJpeg(cgImage: cgImage, quality: quality, source: "imageio")
+	}
+
+	// MARK: - PhotoKit path (display-source — stale-EXIF-resistant)
+
+	private func renderViaPhotoKit(assetId: String, maxLongEdge: Double, quality: Double) throws -> NormalizedImage {
+		let fetch = PHAsset.fetchAssets(withLocalIdentifiers: [assetId], options: nil)
+		guard let asset = fetch.firstObject else {
+			throw NormalizationError.assetNotFound(assetId)
+		}
+
+		let requestOpts = PHImageRequestOptions()
+		requestOpts.isSynchronous = true
+		requestOpts.deliveryMode = .highQualityFormat
+		requestOpts.resizeMode = .exact
+		requestOpts.isNetworkAccessAllowed = true
+
+		var resultImage: UIImage?
+		PHImageManager.default().requestImage(
+			for: asset,
+			targetSize: CGSize(width: maxLongEdge, height: maxLongEdge),
+			contentMode: .aspectFit,
+			options: requestOpts
+		) { image, _ in
+			resultImage = image
+		}
+		guard let uiImage = resultImage else {
+			throw NormalizationError.photoKitFailed
+		}
+
+		let baked = try bakeOrientation(uiImage)
+		return try writeJpeg(cgImage: baked, quality: quality, source: "photo-asset")
+	}
+
+	// MARK: - Helpers
+
+	private func bakeOrientation(_ uiImage: UIImage) throws -> CGImage {
+		// UIGraphicsImageRenderer.draw applies imageOrientation, producing display-space
+		// pixels with .up orientation. format.scale = 1 keeps pixel dims == point dims.
+		if uiImage.imageOrientation == .up, uiImage.scale == 1, let cg = uiImage.cgImage {
+			return cg
+		}
+		let format = UIGraphicsImageRendererFormat()
+		format.scale = 1
+		let renderer = UIGraphicsImageRenderer(size: uiImage.size, format: format)
+		let rendered = renderer.image { _ in
+			uiImage.draw(at: .zero)
+		}
+		guard let cg = rendered.cgImage else {
+			throw NormalizationError.decodeFailed
+		}
+		return cg
+	}
+
+	private func writeJpeg(cgImage: CGImage, quality: Double, source: String) throws -> NormalizedImage {
+		let outputURL = cacheJpegURL()
+		guard let dest = CGImageDestinationCreateWithURL(
+			outputURL as CFURL,
+			UTType.jpeg.identifier as CFString,
+			1,
+			nil
+		) else {
+			throw NormalizationError.destinationFailed
+		}
+
+		let writeOpts: [CFString: Any] = [
+			kCGImageDestinationLossyCompressionQuality: quality,
+			kCGImagePropertyOrientation: 1,
+		]
+		CGImageDestinationAddImage(dest, cgImage, writeOpts as CFDictionary)
+
+		guard CGImageDestinationFinalize(dest) else {
+			throw NormalizationError.encodeFailed
+		}
+
+		let result = NormalizedImage()
+		result.uri = outputURL.absoluteString
+		result.width = Double(cgImage.width)
+		result.height = Double(cgImage.height)
+		result.orientation = 1
+		result.source = source
+		return result
+	}
+
+	private func parseURL(_ uri: String) -> URL? {
+		if let u = URL(string: uri), u.scheme != nil { return u }
+		// Tolerate raw paths.
+		return URL(fileURLWithPath: uri)
+	}
+
+	private func cacheJpegURL() -> URL {
+		let dir = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
+		return dir.appendingPathComponent("normalized_\(UUID().uuidString).jpg")
+	}
+
+	private func validate(_ options: NormalizePickedImageOptions) throws {
+		if options.uri.isEmpty {
+			throw NormalizationError.invalidOptions("uri is required")
+		}
+		if options.maxLongEdge <= 0 {
+			throw NormalizationError.invalidOptions("maxLongEdge must be > 0")
+		}
+	}
+
+	private func clampedQuality(_ q: Double) -> Double {
+		return max(0, min(1, q))
+	}
+}
+
+struct NormalizePickedImageOptions: Record {
+	@Field var uri: String = ""
+	@Field var assetId: String?
+	@Field var mimeType: String?
+	@Field var maxLongEdge: Double = 2000
+	@Field var quality: Double = 0.9
+}
+
+class NormalizedImage: Record {
+	@Field var uri: String = ""
+	@Field var width: Double = 0
+	@Field var height: Double = 0
+	@Field var orientation: Int = 1
+	@Field var source: String = "fallback"
+
+	required init() {}
+}
+
+enum NormalizationError: Error, LocalizedError {
+	case invalidUri(String)
+	case invalidOptions(String)
+	case cannotOpen(String)
+	case decodeFailed
+	case destinationFailed
+	case encodeFailed
+	case assetNotFound(String)
+	case photoKitFailed
+
+	var errorDescription: String? {
+		switch self {
+		case .invalidUri(let uri): return "Invalid URI: \(uri)"
+		case .invalidOptions(let reason): return "Invalid options: \(reason)"
+		case .cannotOpen(let uri): return "Cannot open image source: \(uri)"
+		case .decodeFailed: return "Failed to decode source image"
+		case .destinationFailed: return "Failed to create JPEG destination"
+		case .encodeFailed: return "Failed to encode JPEG output"
+		case .assetNotFound(let id): return "PhotoKit asset not found: \(id)"
+		case .photoKitFailed: return "PhotoKit returned no image"
+		}
+	}
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@rayabelcode/expo-image-orientation-normalizer",
+  "version": "0.9.0",
+  "description": "Native ingress normalization for gallery-picked images on React Native / Expo. Decodes via PhotoKit and ImageIO on iOS, BitmapFactory + ExifInterface + Matrix on Android; writes display-oriented JPEG with EXIF Orientation=1.",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "build",
+    "src",
+    "ios",
+    "android",
+    "expo-module.config.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node internal/module_scripts/build.js",
+    "clean": "node internal/module_scripts/clean.js",
+    "lint": "eslint src/",
+    "test": "node internal/module_scripts/test.js",
+    "prepare": "node internal/module_scripts/prepare.js",
+    "open:ios": "node internal/module_scripts/open-ios.js",
+    "open:android": "node internal/module_scripts/open-android.js"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-modules",
+    "exif",
+    "orientation",
+    "image-picker",
+    "heic",
+    "jpeg",
+    "photokit",
+    "imageio",
+    "exifinterface",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rayabelcode/expo-image-orientation-normalizer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rayabelcode/expo-image-orientation-normalizer/issues"
+  },
+  "author": "Ray Abel (https://github.com/rayabelcode)",
+  "license": "MIT",
+  "homepage": "https://github.com/rayabelcode/expo-image-orientation-normalizer#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@babel/core": "^7.26.0",
+    "@types/jest": "^29.2.1",
+    "@types/react": "~19.1.1",
+    "babel-preset-expo": "~55.0.8",
+    "eslint": "~9.39.4",
+    "eslint-config-universe": "^15.0.3",
+    "expo": "^56.0.3",
+    "jest": "^29.7.0",
+    "jest-expo": "~55.0.9",
+    "prettier": "^3.0.0",
+    "react-native": "0.82.1",
+    "typescript": "^5.9.2"
+  },
+  "jest": {
+    "preset": "jest-expo",
+    "roots": [
+      "<rootDir>/src"
+    ]
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "react": "*",
+    "react-native": "*"
+  }
+}

package/src/ImageOrientationNormalizer.types.ts

@@ -0,0 +1,21 @@
+// Which native render path produced the output. `photo-asset` is display-source
+// (stale-EXIF-resistant via PhotoKit); `imageio` and `exifinterface` are
+// metadata-faithful — they trust the file's EXIF tag and cannot detect a lying
+// tag. `fallback` indicates the stub returned the input URI unchanged.
+export type NormalizationSource = 'photo-asset' | 'imageio' | 'exifinterface' | 'fallback';
+
+export interface NormalizedImage {
+  uri: string;
+  width: number;
+  height: number;
+  orientation: 1;
+  source: NormalizationSource;
+}
+
+export interface NormalizePickedImageOptions {
+  uri: string;
+  assetId?: string;
+  mimeType?: string;
+  maxLongEdge: number;
+  quality: number;
+}

package/src/ImageOrientationNormalizerModule.ts

@@ -0,0 +1,12 @@
+import { NativeModule, requireNativeModule } from 'expo';
+
+import type {
+  NormalizePickedImageOptions,
+  NormalizedImage,
+} from './ImageOrientationNormalizer.types';
+
+declare class ImageOrientationNormalizerModule extends NativeModule<Record<string, never>> {
+  normalizePickedImage(options: NormalizePickedImageOptions): Promise<NormalizedImage>;
+}
+
+export default requireNativeModule<ImageOrientationNormalizerModule>('ImageOrientationNormalizer');

package/src/index.ts

@@ -0,0 +1,25 @@
+// Public entry point for the ImageOrientationNormalizer module.
+//
+// Normalizes a gallery-picked image to a fresh JPEG with display-oriented
+// pixels and EXIF Orientation=1. Throws on hard failure — callers MUST surface
+// the error and cancel; never proceed with the un-normalized input URI.
+//
+// Only the `photo-asset` source (PhotoKit on iOS when an assetId is provided)
+// is stale-EXIF-resistant. The `imageio` and `exifinterface` paths are
+// metadata-faithful — they trust the file's EXIF tag and cannot detect a
+// lying tag.
+
+import type {
+  NormalizePickedImageOptions,
+  NormalizedImage,
+  NormalizationSource,
+} from './ImageOrientationNormalizer.types';
+import ImageOrientationNormalizerModule from './ImageOrientationNormalizerModule';
+
+export type { NormalizePickedImageOptions, NormalizedImage, NormalizationSource };
+
+export function normalizePickedImage(
+  options: NormalizePickedImageOptions
+): Promise<NormalizedImage> {
+  return ImageOrientationNormalizerModule.normalizePickedImage(options);
+}