四点框住斜拍照,一裁校正。
文档、快递单、白板——从透视畸变里拉回正视。Kuikly Compose DSL 多端库,Android / iOS / 鸿蒙 / H5 同一套 API。
不做 OCR,不做自动扫边;检到的点可以直接灌进来。
| 项 | 值 |
|---|---|
| 发布模块 | KuiklyPerspectiveCropCore |
| 包名 | com.jlj.kuiklybase.perspectivecrop |
| Maven 坐标 | io.github.sofarnobug:KuiklyPerspectiveCropCore:1.0.0-2.30.0 |
| Kuikly | 2.30.0-2.1.21(经腾讯 Maven 镜像拉取) |
本文件给接入方。维护本仓(起服、里程碑、ADR)见 CONTRIBUTING.md。
- 已有 Kuikly Compose 宿主工程(本库不是独立 App SDK)。
- 宿主能解析 同一 Kuikly 版本(
2.30.0-2.1.21);公开 API 经api传递 Kuikly Compose。 - 出图前按端完成 初始化(见下;H5 除外);否则抛
CropException(code = NOT_INITIALIZED)。
本库不做 OCR、边缘检测或内置 autoScan。外部检测结果可通过 writePoints / applyAutoScanPoints 注入四点。
| 端 | 必加 | 原生放大镜另加 | 接完成功标准 |
|---|---|---|---|
| Android | Maven Core | 无(Core 内 BitmapShader) |
init 后 cropToFile() 出路径;拖角见清晰圆镜 |
| iOS | Maven Core(进 KN framework) | CocoaPods KuiklyPerspectiveCrop 1.0.0 |
init(cacheDir) 后可落盘;拖角见圆镜像素(非灰底) |
| 鸿蒙 | Maven Core(ohosArm64) | ohpm @jlj/kuikly-perspective-crop-ohos@1.0.0 |
init + 注册 View + blit;拖角见圆镜 |
| H5 | Maven Core(JS 变体) | 无单独 npm/H5 包 | 无需 PerspectiveCrop*.init;cropToFile() 得 blob:;镜为网格兜底 |
版本后缀与 Kuikly 对齐:1.0.0-2.30.0 ↔ Kuikly 2.30.0-2.1.21。CocoaPods / ohpm 主版本与库主版本对齐为 1.0.0(无 -2.30.0 后缀)。
repositories {
mavenCentral()
maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-tencent/") }
}
dependencies {
implementation("io.github.sofarnobug:KuiklyPerspectiveCropCore:1.0.0-2.30.0")
}把 Core 编进宿主的 Kotlin Multiplatform / Kuikly 共享模块(或 Android 直接依赖)。不要只加原生 Pod/HAR 却不加 Core——裁切与 Stage 在 Core 里。
相机 filePath / 相册 uri / assets
↓ imageSrc: String
PerspectiveCropStage // Image + 叠层框选 + 放大镜
↓ suspend
crop() → PlatformImage 或 cropToFile() → String
出图 / saveToFile 前必须按端初始化(H5 除外)。
依赖:仅 Maven Core。
落点:Application.onCreate(或等价最早入口)。
import com.jlj.kuiklybase.perspectivecrop.PerspectiveCropAndroid
class App : Application() {
override fun onCreate() {
super.onCreate()
PerspectiveCropAndroid.init(this)
}
}依赖:
- 共享 KN 模块:
implementation("…KuiklyPerspectiveCropCore:1.0.0-2.30.0"),并在产生 framework 时 export Core(让壳运行时能取到PerspectiveCropIosMagnifierBridge)。 - App
Podfile另加原生镜:
pod 'KuiklyPerspectiveCrop', '1.0.0'落点:App 启动时注入可写缓存目录(cropToFile / saveToFile 用):
// 推荐:KN 暴露的桥(本仓 Demo:PerspectiveCropIosBridge)
let caches = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first!
PerspectiveCropIosBridge.shared.configure(cacheDir: caches.path)等价 Kotlin:PerspectiveCropIos.init(cacheDir)。
说明:
- 类名
KRPerspectiveCropMagnifier由 Kuikly 按名解析,无需registerExternalRenderView。 - 壳经 ObjC 名
PerspectiveCropIosMagnifierBridge读 blit;若未 link / 未 export Core,圆镜会灰底无像素。 assets://在 main Bundle 与已加载 Bundle 中按资源名查找。
依赖:
- KMP ohosArm64:Maven Core
1.0.0-2.30.0。 - 原生镜:
ohpm install @jlj/kuikly-perspective-crop-ohos@1.0.0落点(三处都要):
- Kotlin:
PerspectiveCropOhos.init(resfileDir, cacheDir)(resfileDir解assets://;cacheDir可空,空则带 path 的saveToFile会失败)。本仓 Demo 经perspectiveCropDemo/.../PerspectiveCropOhosNative.kt从壳转发。 - 注册 View(
KuiklyViewDelegate):
import { KRPerspectiveCropMagnifierView } from '@jlj/kuikly-perspective-crop-ohos';
map.set(
KRPerspectiveCropMagnifierView.VIEW_NAME,
() => new KRPerspectiveCropMagnifierView(),
);- 注入 blit(宿主 so 须导出
getMagnifierBlit,可对照 Demolibentry):
import {
KRPerspectiveCropMagnifierView,
PerspectiveCropOhosNative,
} from '@jlj/kuikly-perspective-crop-ohos';
import Napi from 'libentry.so';
PerspectiveCropOhosNative.configure(() => Napi.getMagnifierBlit());- 只依赖 Maven Core 的 JS 变体;没有单独 npm / H5 壳包。
- 无
PerspectiveCropAndroid/Ios/Ohos.init。 cropToFile()成功时常返回blob:ObjectURL,可再赋给预览imageSrc;刷新或 revoke 后失效。- 放大镜目前为采样缓存 + 网格绘制兜底(非原生贴图)。
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberCoroutineScope
import com.jlj.kuiklybase.perspectivecrop.CropException
import com.jlj.kuiklybase.perspectivecrop.PerspectiveCropStage
import com.jlj.kuiklybase.perspectivecrop.rememberPerspectiveCropController
import com.tencent.kuikly.compose.foundation.layout.fillMaxSize
import com.tencent.kuikly.compose.ui.Modifier
import kotlinx.coroutines.launch
@Composable
fun CropPage(imageSrc: String) {
val controller = rememberPerspectiveCropController()
val scope = rememberCoroutineScope()
PerspectiveCropStage(
modifier = Modifier.fillMaxSize(),
controller = controller,
imageSrc = imageSrc, // 或先 controller.applyImageSrc(src)
)
// 确认裁切(按钮 onClick 里调用)
fun onConfirm() {
scope.launch {
try {
val outSrc = controller.cropToFile()
// 展示 outSrc
} catch (e: CropException) {
// "${e.code}: ${e.message}"
}
}
}
}常用命令:controller.resetFullImage()、controller.rotateClockwise()、controller.canCrop()、controller.updateConfig(…)。
完整最小页:perspectiveCropDemo/.../demo/PerspectiveCropDemoPager.kt。
- 依赖:该端「必加」已进工程;需要镜的端「另加」也已进。
- 启动后完成对应
init/ 注册 / blit(H5 跳过)。 - 设好
imageSrc→ 拖角/边 → 点确认 →cropToFile()有路径或blob:,失败为带code的CropException(不静默成功)。 - Android / iOS / 鸿蒙:拖角圆镜应见贴图像素;H5 可为网格。
| 坑 | 典型现象 | 怎么避 |
|---|---|---|
| 只加 CocoaPods / ohpm,不加 Maven Core | 没有 Stage / 裁切 API | Core 必加;原生包只补放大镜壳 |
未按端 init(H5 除外) |
CropException(NOT_INITIALIZED) / 落盘失败 |
Android Application;iOS 启动注入 cacheDir;鸿蒙 init + 壳转发 |
| iOS 未 export Core / 桥链不上 | 圆镜灰底、无贴图像素 | KN framework export Core;开 xcworkspace;Pod KuiklyPerspectiveCrop |
iOS 打开裸 xcodeproj |
Pod / KN 链失败 | 必须 *.xcworkspace |
鸿蒙未 map.set 放大镜 View |
无镜或占位异常 | KuiklyViewDelegate 注册 KRPerspectiveCropMagnifierView |
鸿蒙未 PerspectiveCropOhosNative.configure(blit) |
黑镜 / 无像素 | 宿主 so 导出 getMagnifierBlit 并 configure |
showOperationUI = false 当成「只藏手柄」 |
六层叠层 + 原生镜整包不画;手势仍可用 | 要隐藏操作 UI 才关;细控用 showMagnifier 等 |
把 config.toViewPx(density) 再 updateConfig |
框线/命中区被放大两次 | 公开 Config 保持 dp;lengthsAreViewPx 不是产品开关 |
H5 当持久文件路径用 cropToFile() |
刷新后预览失效 | 返回常为 blob:,需立刻展示或自行转存 |
| 期望 H5 原生清晰镜 | 只有网格兜底 | 当前设计如此;清晰镜看 Android / iOS / 鸿蒙 |
imageSrc 协议错 / H5 跨域无 CORS |
DECODE_FAILED |
核对 file:// / content:// / assets:// / 可访问 URL |
| 业务皮肤写进库默认 Painter | 升级被覆盖、污染默认主题 | 皮肤只放宿主;用六层 SPI 注入 |
Android 折叠开合未声明 configChanges |
Activity 重建 → Kuikly 页重挂,Compose remember 全丢(像回首页) |
宿主 Activity 对齐 KuiklyUI:configChanges 含 screenSize / smallestScreenSize / screenLayout / orientation;尺寸由 rootViewSizeDidChanged 刷新。本仓 Demo 已加;接入方勿漏 |
| iPhone Duo 摄像头挖孔压住顶栏/Chip | Lab「外观」Chip 或状态区落在黑圆上 | 读 pageData.reservedRegions 中生效的 OCCLUSION 自行垫开(非 Core Config)。本仓 Lab 默认开「遮挡避让」;最小 Demo 始终避让。宿主业务页须自己订阅,库不会代垫 |
Demo 起服级排障(白屏、webpack、UMD 等)见 CONTRIBUTING.md 与各端 runbook,不在本表展开。
库不强制依赖相机/相册;把路径或 uri 交给 Controller 即可:
// 相机:KuiklyCamera → onPhotoCaptured { filePath -> … }
controller.applyImageSrc(filePath) // 或 file://$filePath
// 相册:KuiklyPhotoSelector → KRAlbumImage.uri
controller.applyImageSrc(uri) // content://… / file://…
PerspectiveCropStage(controller = controller, imageSrc = controller.imageSrc)suspend fun crop(): PlatformImage
suspend fun cropToFile(): String
suspend fun cropToFile(path: String): String失败抛 CropException(code, message, cause?),不会静默回原图或返回可空假成功。
code |
含义 |
|---|---|
EMPTY_IMAGE_SRC |
未设 imageSrc |
ILLEGAL_POINTS |
四点非法(可先查 canCrop()) |
NOT_INITIALIZED |
未调用对应端 init |
DECODE_FAILED |
原图解码失败 |
TRANSFORM_FAILED |
透视变换失败 |
WRITE_FAILED |
落盘失败(含空 path) |
UNSUPPORTED_PLATFORM |
当前端/引擎组合不支持 |
| 端 | cropEngine(默认 Auto) |
放大镜 |
|---|---|---|
| Android | Auto/Native → setPolyToPoly;Common → CPU 单应 |
原生贴图(BitmapShader) |
| iOS | Auto/Native → Core Image 四点透视;Common → CPU 单应 | 原生贴图(MagnifierBlitStore + 壳桥) |
| 鸿蒙 | Auto/Native → Drawing SetPolyToPoly;Common → CPU 单应 |
原生贴图(Blit + NAPI 快照) |
| H5 | 始终 Common(CPU 单应);cropToFile 可返回 blob: |
采样缓存 + 网格绘制兜底 |
CropEngine.Native 在无原生路径的端上会明确失败(带 CropException),不会假装成功。
产品页一般用默认即可。UI 长度字段为 Compose dp(Stage 内经 density 换算);cornerMaxStepPx、magnifierCacheMaxEdgePx 为像素语义,不按 dp 缩放。
| 字段 | 默认 | 说明 | 何时用 |
|---|---|---|---|
rectMode |
false |
自由四边形 ↔ 轴对齐矩形 | 要矩形裁剪时开 |
edgeSnapToTouchEnabled |
true |
矩形模式拖边吸到触点 | 仅 rectMode 有感;边要跟指尖走时保持开 |
edgeClampToBoundsEnabled |
true |
拖边顶到图边时两端齐步、不斜边(自由/矩形均生效) | 不要到边斜掉 → 保持开 |
insideDragEnabled |
true |
框内拖整框 | 不要框内平移时关 |
unhitPassthrough |
false |
DOWN 未命中手柄时交给父容器 | 嵌横滑页、要点空白翻页时开 |
touchCornerCatchDistance |
20 |
角命中半径(dp;≤0 关闭) | 角难点 → 加大;禁角拖 → 0 |
touchEdgeCatchDistance |
20 |
边命中带宽(dp;≤0 关闭) | 边难抓 → 加大 |
touchMidCatchDistance |
30 |
边中点命中半径(dp;≤0 关闭) | 开了中点绘制后再调 |
touchEdgeProjectionError |
100 |
抓边沿边外延(dp) | 宽松默认;严谨须贴边线段 → 0(仍可抓边,非仅中点) |
minCropWidth |
100 |
最小边长(dp) | 允许更小框 → 调小;防缩没 → 调大 |
minAngleLimit |
20 |
最小内角(度);0 不校验 |
要更严/更松的凸性约束时调 |
cornerGrabOffsetEnabled |
false |
自由角保留「手指−角点」按压偏移 | 多数不用;默认帧增量即可 |
cornerMaxStepPx |
0 |
自由角单帧最大位移(图像素;≤0 不限) | 甩动大跳时再限 |
contentInsetLeft/Top/Right/Bottom |
0 |
内容区内缩(dp;蒙版仍满屏) | 裁剪区外还要摆控件时开 |
showOperationUI |
true |
绘制选区操作 UI(六层叠层 + 原生镜) | 只要底图/仍可拖 → 关(对齐旧库 hideOperationUI 取反) |
showMagnifier |
true |
绘制放大镜 | 不要镜 → 关 |
showGuideLines |
false |
九宫格(整图 Fit) | 要构图辅助线 → 开 |
showEdgeMidPoints |
false |
绘制边线中点 | 要边上圆点 → 开;关后仍可拖边 |
showCornerBorder |
true |
角点描边 | 白实心无红圈 → 关 |
showMagnifierCropLineMirror |
true |
镜内再画裁剪框线段 | 镜里只要图 → 关 |
showMagnifierCenterCross |
false |
镜心十字 | 要对准像素 → 开 |
magnifierRadiusRatio |
0.07 |
镜半径占视图宽比 | 调镜大小 |
magnifierBorderWidth / magnifierBorderColor |
2 / 白 |
镜边框 | 换皮时调 |
magnifierCrossColor / magnifierCrossLineWidth / magnifierCrossLineLength |
白 / 3 / 15 |
十字样式(dp) | 开了十字再调 |
magnifierPlacement |
TopAutoFlip |
圆镜摆放 | 挡内容时改 TopLeft / TopRight / AboveTouch |
magnifierCacheMaxEdgePx |
2048 |
采样缓存最长边(真实 px) | 低端卡/省内存 → 1024 |
maskAlpha |
0.55 |
蒙版透明度 | 换品牌皮 |
borderWidthPx / borderColor |
2 / 红 |
框线(字段名历史遗留,语义为 dp) | 换皮 |
cornerRadiusPx |
8 |
角点半径(dp) | 换皮 |
cornerFillColor / cornerFillAlpha |
白 / 1 |
角点填充(ARGB + 0–1 α) | Accent Ring 默认白芯 |
cornerBorderWidth / cornerBorderColor |
2 / 红 |
角点描边(dp;须 showCornerBorder) |
换皮 |
guideLineWidth / guideLineColor |
1 / 半透明白 |
辅助线 | 开了九宫格再调 |
outputFormat / jpegQuality |
Jpeg / 92 |
导出格式与 JPEG 质量 | 要 PNG 或调质量时 |
cropEngine |
Auto |
出图引擎:Auto / Native / Common |
强制原生或强制 CPU 时改 |
警告:不要把 config.toViewPx(density) 的结果再传给 updateConfig / Session;公开配置保持 dp。lengthsAreViewPx 是库内防双重放大标记,不是产品开关。
controller.updateConfig(
controller.config.copy(rectMode = true, showGuideLines = true),
)四点为图像素,顺序 TL → TR → BR → BL:
controller.writePoints(listOf(tl, tr, br, bl))
// 或
controller.applyAutoScanPoints(listOf(tl, tr, br, bl)) // 等价别名叠层分为蒙版 / 框线 / 角点 / 边中点 / 辅助线 / 放大镜,可单独替换;门面:
import com.jlj.kuiklybase.perspectivecrop.overlay.CropOverlayPainters
import com.jlj.kuiklybase.perspectivecrop.overlay.BorderOverlayPainter
// Mask / Corner / EdgeMid / Guide / Magnifier 同理
val painters = CropOverlayPainters(
border = BorderOverlayPainter { viewPoints, config ->
// DrawScope 内自绘框线
},
// 其余层省略则用 Default*OverlayPainter
)
controller.updatePainters(painters)
// 或 PerspectiveCropStage(..., painters = painters)
// 或 rememberPerspectiveCropController(painters = painters)接口:MaskOverlayPainter、BorderOverlayPainter、CornerOverlayPainter、EdgeMidOverlayPainter、GuideOverlayPainter、MagnifierOverlayPainter。
完整换皮示例见 Demo Lab:perspectiveCropDemo/.../demo/LabSkinPainters.kt、PerspectiveCropLabPager.kt。业务皮肤放在宿主/Demo,不要改库默认实现。
| pageName | 角色 |
|---|---|
perspective_crop_demo |
最小实现(框选 + 确认裁切) |
perspective_crop_lab |
全能 Lab(Toggle / 换皮 / 缓存边长 / writePoints) |
源码目录:perspectiveCropDemo/src/commonMain/kotlin/.../demo/。
本仓快速看一眼(需 JDK 17):
./gradlew :androidApp:installDebugH5 / 鸿蒙 / iOS 起服与排障见 CONTRIBUTING.md。