از 27 مارس 2025، توصیه می کنیم از android-latest-release به جای aosp-main برای ساختن و کمک به AOSP استفاده کنید. برای اطلاعات بیشتر، به تغییرات AOSP مراجعه کنید.
جریان خروجی، برش، و زوم
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
جریان های خروجی
زیرسیستم دوربین فقط بر روی خط لوله مبتنی بر ANativeWindow برای همه وضوح‌ها و فرمت‌های خروجی کار می‌کند. چندین جریان را می توان در یک زمان پیکربندی کرد تا یک فریم را به اهداف زیادی مانند GPU، رمزگذار ویدیو، RenderScript یا بافرهای قابل مشاهده برنامه (RAW Bayer، بافرهای YUV پردازش شده، یا بافرهای رمزگذاری شده با JPEG) ارسال کند.
به عنوان یک بهینه‌سازی، این جریان‌های خروجی باید زودتر از موعد پیکربندی شوند و ممکن است تعداد محدودی هم‌زمان وجود داشته باشد. این امکان پیش‌تخصیص بافرهای حافظه و پیکربندی سخت‌افزار دوربین را فراهم می‌کند، به طوری که وقتی درخواست‌ها با خطوط لوله خروجی متعدد یا متفاوت ارائه می‌شوند، تاخیر یا تاخیری در انجام درخواست وجود نداشته باشد.
برای اطلاعات بیشتر در مورد ترکیب‌های خروجی جریان تضمین شده که به سطح سخت‌افزار پشتیبانی‌شده بستگی دارد، به createCaptureSession() مراجعه کنید.
برداشت
برش آرایه پیکسل کامل (برای زوم دیجیتال و سایر موارد استفاده که در آن FOV کوچکتر مطلوب است) از طریق تنظیم ANDROID_SCALER_CROP_REGION اطلاع رسانی می شود. این یک تنظیم برای هر درخواست است و می‌تواند بر اساس هر درخواست تغییر کند، که برای پیاده‌سازی بزرگنمایی دیجیتال روان بسیار مهم است.
منطقه به عنوان یک مستطیل (x، y، عرض، ارتفاع) تعریف می شود که (x، y) گوشه سمت چپ بالای مستطیل را توصیف می کند. مستطیل بر روی سیستم مختصات آرایه پیکسل فعال حسگر تعریف شده است که (0,0) پیکسل بالای سمت چپ آرایه پیکسل فعال است. بنابراین، عرض و ارتفاع نمی‌تواند بزرگ‌تر از ابعاد گزارش‌شده در قسمت اطلاعات ثابت ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY باشد. حداقل عرض و ارتفاع مجاز توسط HAL از طریق فیلد اطلاعات ثابت ANDROID_SCALER_MAX_DIGITAL_ZOOM گزارش می شود که حداکثر ضریب بزرگنمایی پشتیبانی شده را توصیف می کند. بنابراین، حداقل عرض و ارتفاع منطقه محصول عبارتند از:
{width, height} =
{ floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[0] /
ANDROID_SCALER_MAX_DIGITAL_ZOOM),
floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[1] /
ANDROID_SCALER_MAX_DIGITAL_ZOOM) }
اگر منطقه محصول نیاز به برآورده کردن الزامات خاص داشته باشد (برای مثال، باید از مختصات زوج شروع شود، و عرض/ارتفاع آن باید یکنواخت باشد)، HAL باید گرد کردن لازم را انجام دهد و منطقه برش نهایی مورد استفاده در فراداده نتیجه خروجی را بنویسد. به طور مشابه، اگر HAL تثبیت‌کننده ویدیو را پیاده‌سازی کند، باید ناحیه برش نتیجه را برای توصیف منطقه‌ای که واقعاً در خروجی پس از اعمال تثبیت‌کننده ویدیو گنجانده شده است، تنظیم کند. به طور کلی، برنامه ای که از دوربین استفاده می کند باید بتواند بر اساس ناحیه برش، ابعاد حسگر تصویر و فاصله کانونی لنز، میدان دیدی را که دریافت می کند، تعیین کند.
از آنجایی که منطقه برش برای همه جریان‌ها اعمال می‌شود، که ممکن است نسبت‌های ابعادی متفاوتی نسبت به منطقه برش داشته باشند، منطقه حسگر دقیق استفاده‌شده برای هر جریان ممکن است کوچکتر از منطقه برداشت باشد. به طور خاص، هر جریان باید پیکسل‌های مربعی و نسبت ابعاد آن را با برش بیشتر منطقه برش تعریف‌شده حفظ کند. اگر نسبت ابعاد جریان بیشتر از ناحیه برش باشد، جریان باید بیشتر به صورت عمودی برش داده شود و اگر نسبت ابعاد جریان باریکتر از منطقه برش باشد، جریان باید بیشتر به صورت افقی برش داده شود.
در همه موارد، محصول جریان باید در مرکز منطقه کامل محصول باشد، و هر جریان فقط به صورت افقی یا عمودی نسبت به منطقه کامل محصول برش داده می شود، نه هر دو.
برای مثال، اگر دو جریان تعریف شده باشد، یک جریان 640x480 (وجهه 4:3) و یک جریان 1280x720 (وجهه 16:9)، در زیر مناطق خروجی مورد انتظار برای هر جریان را برای چند منطقه برش نمونه، روی یک آرایه سنسور 3 مگاپیکسلی (2000 x 1500 پیکسل) فرضی نشان می‌دهد.
منطقه برش: (500، 375، 1000، 750) (نسبت تصویر 4:3)
برش جریان 640x480: (500، 375، 1000، 750) (برابر با منطقه محصول)
برش جریان 1280x720: (500، 469، 1000، 562)
شکل 1. نسبت تصویر 4:3
منطقه برش: (500، 375، 1333، 750) (نسبت تصویر 16:9)
برش جریان 640x480: (666، 375، 1000، 750)
برش جریان 1280x720: (500، 375، 1333، 750) (برابر با منطقه محصول)
شکل 2. نسبت تصویر 16:9
منطقه برش: (500، 375، 750، 750) (نسبت تصویر 1:1)
برش جریانی 640x480: (500، 469، 750، 562)
برش جریان 1280x720: (500، 543، 750، 414)
شکل 3. نسبت تصویر 1:1
و یک مثال آخر، یک جریان با نسبت ابعاد مربعی 1024x1024 به جای جریان 480p:
منطقه برش: (500، 375، 1000، 750) (نسبت تصویر 4:3)
برش جریانی 1024x1024: (625، 375، 750، 750)
برش جریان 1280x720: (500، 469، 1000، 562)
شکل 4. نسبت تصویر 4:3، مربع
پردازش مجدد
پشتیبانی اضافی برای فایل های تصویر خام با پشتیبانی از پردازش مجدد داده های RAW Bayer ارائه می شود. این پشتیبانی به خط لوله دوربین اجازه می‌دهد تا یک بافر و ابرداده RAW قبلاً گرفته شده را پردازش کند (کل فریمی که قبلاً ضبط شده است) تا خروجی YUV یا JPEG رندر شده جدیدی تولید کند.
بزرگنمایی ضربه بزنید؛
برای دستگاه‌های دارای Android 11 یا بالاتر، یک برنامه می‌تواند از زوم دوربین (دیجیتال و اپتیکال) از طریق تنظیم ANDROID_CONTROL_ZOOM_RATIO استفاده کند.
نسبت بزرگنمایی به عنوان یک ضریب ممیز شناور تعریف می شود. به‌جای استفاده از ANDROID_SCALER_CROP_REGION برای برش و بزرگنمایی، یک برنامه می‌تواند از ANDROID_CONTROL_ZOOM_RATIO برای کنترل سطح بزرگنمایی استفاده کند و از ANDROID_SCALER_CROP_REGION برای برش افقی و عمودی برای دستیابی به نسبت‌هایی متفاوت از حسگر دوربین اصلی استفاده کند.
یک سیستم چند دوربینی ممکن است حاوی بیش از یک لنز با فواصل کانونی متفاوت باشد و کاربر می تواند با جابجایی بین لنزها از زوم اپتیکال استفاده کند. استفاده از ANDROID_CONTROL_ZOOM_RATIO در سناریوهای زیر مزایایی دارد:
- بزرگنمایی از یک لنز واید به یک لنز تله فوتو: نسبت ممیز شناور در مقایسه با مقادیر صحیح
ANDROID_SCALER_CROP_REGION دقت بهتری را ارائه می دهد. - بزرگنمایی از یک لنز عریض به یک لنز فوق عریض:
ANDROID_CONTROL_ZOOM_RATIO از بزرگنمایی (<1.0f) پشتیبانی می کند در حالی که ANDROID_SCALER_CROP_REGION این کار را نمی کند.
برای نشان دادن، در اینجا چندین سناریو از نسبت‌های بزرگنمایی مختلف، مناطق برش و جریان‌های خروجی، با استفاده از همان دوربین فرضی تعریف‌شده در بخش قبل، وجود دارد.
نسبت بزرگنمایی: 2.0; 1/4 میدان دید اصلی
منطقه برش: (0، 0، 2000، 1500) (نسبت تصویر 4:3)
برش جریان 640x480: (0، 0، 2000، 1500) (برابر با منطقه برش)
برش جریان 1280x720: (0، 187، 2000، 1125)
شکل 5. زوم 2.0، نسبت تصویر 4:3
نسبت بزرگنمایی: 2.0; 1/4 میدان دید اصلی
منطقه برش: (0، 187، 2000، 1125) (نسبت تصویر 16:9)
برش جریانی 640x480: (250، 187، 1500، 1125) (با جعبه ستونی)
برش جریان 1280x720: (0، 187، 2000، 1125) (برابر با منطقه برش)
شکل 6. زوم 2.0، نسبت تصویر 16:9
نسبت بزرگنمایی: 0.5; 4 برابر میدان دید اصلی (تغییر از لنز واید به لنز فوق عریض)
منطقه برش: (250، 0، 1500، 1500) (نسبت تصویر 1:1)
برش جریانی 640x480: (250، 187، 1500، 1125) (با جعبه نامه)
برش جریانی 1280x720: (250، 328، 1500، 844) (با جعبه نامه)
شکل 7. زوم 0.5، نسبت تصویر 1:1
همانطور که از نمودارهای بالا مشاهده می شود، سیستم مختصات ناحیه برش به میدان دید موثر پس از زوم تغییر می کند و با مستطیل با ابعاد زیر نشان داده می شود: ( 0 ، 0 ، activeArrayWith ، activeArrayHeight ). همین امر در مورد مناطق و چهره های AE/AWB/AF نیز صدق می کند. این تغییر سیستم مختصات برای ضبط RAW و ابرداده‌های مرتبط با آن مانند intrinsicCalibration و lensShadingMap اعمال نمی‌شود.
با استفاده از همان مثال فرضی بالا، و با فرض اینکه جریان خروجی #1 (640x480) جریان منظره یاب است، زوم 2.0 برابری را می توان به یکی از دو روش به دست آورد:
-
zoomRatio = 2.0 ، scaler.cropRegion = (0, 0, 2000, 1500) -
zoomRatio = 1.0 (پیش‌فرض)، scaler.cropRegion = (500, 375, 1000, 750)
برای اینکه برنامه‌ای که android.control.aeRegions به عنوان یک چهارم سمت چپ بالای میدان دید نمایاب تنظیم کند، android.control.aeRegions را روی (0, 0, 1000, 750) با android.control.zoomRatio روی 2.0 تنظیم کنید. از طرف دیگر، این برنامه می‌تواند android.control.aeRegions به منطقه معادل (500, 375, 1000, 750) برای android.control.zoomRatio 1.0 تنظیم کند.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-06-12 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-06-12 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Output streams, cropping, and zoom\n\nOutput streams\n--------------\n\nThe camera subsystem operates solely on the ANativeWindow-based pipeline for\nall resolutions and output formats. Multiple streams can be configured at\none time to send a single frame to many targets such as the GPU, the video\nencoder,\n[RenderScript](/docs/core/architecture/vndk/renderscript),\nor app-visible buffers (RAW Bayer, processed YUV\nbuffers, or JPEG-encoded buffers).\n\nAs an optimization, these output streams must be configured ahead of time, and\nonly a limited number may exist at once. This allows for pre-allocation of\nmemory buffers and configuration of the camera hardware, so that when requests\nare submitted with multiple or varying output pipelines listed, there won't be\ndelays or latency in fulfilling the request.\n\nFor further information about the guaranteed stream output combinations\nthat depend on the supported hardware level, see\n[createCaptureSession()](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createCaptureSession(java.util.List%3Candroid.view.Surface%3E,%20android.hardware.camera2.CameraCaptureSession.StateCallback,%20android.os.Handler)).\n\nCropping\n--------\n\nCropping of the full pixel array (for digital zoom and other use cases where a\nsmaller FOV is desirable) is communicated through the ANDROID_SCALER_CROP_REGION\nsetting. This is a per-request setting, and can change on a per-request basis,\nwhich is critical for implementing smooth digital zoom.\n\nThe region is defined as a rectangle (x, y, width, height), with (x, y)\ndescribing the top-left corner of the rectangle. The rectangle is defined on the\ncoordinate system of the sensor active pixel array, with (0,0) being the\ntop-left pixel of the active pixel array. Therefore, the width and height cannot\nbe larger than the dimensions reported in the ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY\nstatic info field. The minimum allowed width and height are reported by the HAL\nthrough the ANDROID_SCALER_MAX_DIGITAL_ZOOM static info field, which describes\nthe maximum supported zoom factor. Therefore, the minimum crop region width and\nheight are: \n\n```\n {width, height} =\n { floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[0] /\n ANDROID_SCALER_MAX_DIGITAL_ZOOM),\n floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[1] /\n ANDROID_SCALER_MAX_DIGITAL_ZOOM) }\n```\n\nIf the crop region needs to fulfill specific requirements (for example, it needs\nto start on even coordinates, and its width/height needs to be even), the HAL\nmust do the necessary rounding and write out the final crop region used in the\noutput result metadata. Similarly, if the HAL implements video stabilization, it\nmust adjust the result crop region to describe the region actually included in\nthe output after video stabilization is applied. In general, a camera-using\napp must be able to determine the field of view it is receiving based on\nthe crop region, the dimensions of the image sensor, and the lens focal length.\n\nSince the crop region applies to all streams, which may have different aspect\nratios than the crop region, the exact sensor region used for each stream may be\nsmaller than the crop region. Specifically, each stream should maintain square\npixels and its aspect ratio by minimally further cropping the defined crop\nregion. If the stream's aspect ratio is wider than the crop region, the stream\nshould be further cropped vertically, and if the stream's aspect ratio is\nnarrower than the crop region, the stream should be further cropped\nhorizontally.\n\nIn all cases, the stream crop must be centered within the full crop region, and\neach stream is only either cropped horizontally or vertical relative to the full\ncrop region, never both.\n\nFor example, if two streams are defined, a 640x480 stream (4:3 aspect), and a\n1280x720 stream (16:9 aspect), below demonstrates the expected output regions\nfor each stream for a few sample crop regions, on a hypothetical 3 MP (2000 x\n1500 pixel array) sensor.\n\n\nCrop region: (500, 375, 1000, 750) (4:3 aspect ratio) \n\n640x480 stream crop: (500, 375, 1000, 750) (equal to crop region) \n\n1280x720 stream crop: (500, 469, 1000, 562)\n\n\n**Figure 1.** 4:3 aspect ratio\n\nCrop region: (500, 375, 1333, 750) (16:9 aspect ratio) \n\n640x480 stream crop: (666, 375, 1000, 750) \n\n1280x720 stream crop: (500, 375, 1333, 750) (equal to crop region)\n\n\n**Figure 2.** 16:9 aspect ratio\n\nCrop region: (500, 375, 750, 750) (1:1 aspect ratio) \n\n640x480 stream crop: (500, 469, 750, 562) \n\n1280x720 stream crop: (500, 543, 750, 414)\n\n\n**Figure 3.** 1:1 aspect ratio\n\n\nAnd a final example, a 1024x1024 square aspect ratio stream instead of the 480p\nstream: \n\nCrop region: (500, 375, 1000, 750) (4:3 aspect ratio) \n\n1024x1024 stream crop: (625, 375, 750, 750) \n\n1280x720 stream crop: (500, 469, 1000, 562)\n\n\n**Figure 4.** 4:3 aspect ratio, square\n\nReprocessing\n------------\n\nAdditional support for raw image files is provided by reprocessing support for RAW Bayer\ndata. This support allows the camera pipeline to process a previously captured\nRAW buffer and metadata (an entire frame that was recorded previously), to\nproduce a new rendered YUV or JPEG output.\n\nZoom\n----\n\nFor devices running Android 11 or higher, an app can use a camera's zoom\n(digital and optical) through the `ANDROID_CONTROL_ZOOM_RATIO` setting.\n\nThe zoom ratio is defined as a floating point factor. Instead of\nusing `ANDROID_SCALER_CROP_REGION` for crop and zoom, an app can use\n`ANDROID_CONTROL_ZOOM_RATIO` to control the zoom level, and use\n`ANDROID_SCALER_CROP_REGION` for horizontal and vertical cropping to\nachieve aspect ratios different than the native camera sensor.\n\nA multi-camera system may contain more than one lens with different\nfocal lengths, and the user can use optical zoom by switching between lenses.\nUsing `ANDROID_CONTROL_ZOOM_RATIO` has benefits in the scenarios below:\n\n- Zooming in from a wide lens to a telephoto lens: A floating point ratio provides better precision compared to integer values of `ANDROID_SCALER_CROP_REGION`.\n- Zooming out from a wide lens to an ultrawide lens: `ANDROID_CONTROL_ZOOM_RATIO` supports zoom-out (\\\u003c1.0f) whereas `ANDROID_SCALER_CROP_REGION` doesn't.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nTo illustrate, here are several scenarios of different zoom ratios, crop regions, and output streams, using the same hypothetical camera defined in the previous section.\n\n\u003cbr /\u003e\n\n\nZoom ratio: 2.0; 1/4 of original field of view \n\nCrop region: (0, 0, 2000, 1500) (4:3 aspect ratio) \n\n640x480 stream crop: (0, 0, 2000, 1500) (equal to crop region) \n\n1280x720 stream crop: (0, 187, 2000, 1125)\n\n\n**Figure 5.** 2.0 zoom, 4:3 aspect ratio\n\nZoom ratio: 2.0; 1/4 of original field of view \n\nCrop region: (0, 187, 2000, 1125) (16:9 aspect ratio) \n\n640x480 stream crop: (250, 187, 1500, 1125) (pillarboxed) \n\n1280x720 stream crop: (0, 187, 2000, 1125) (equal to crop region)\n\n\n**Figure 6.** 2.0 zoom, 16:9 aspect ratio\n\nZoom ratio: 0.5; 4x of original field of view (switched from wide lens to ultrawide lens) \n\nCrop region: (250, 0, 1500, 1500) (1:1 aspect ratio) \n\n640x480 stream crop: (250, 187, 1500, 1125) (letterboxed) \n\n1280x720 stream crop: (250, 328, 1500, 844) (letterboxed)\n\n\n**Figure 7.** 0.5 zoom, 1:1 aspect ratio\n\nAs seen from the graphs above, the coordinate system of the crop region changes to the effective\nafter-zoom field of view, and is represented by the rectangle with the following dimensions:\n(`0`, `0`, `activeArrayWith`, `activeArrayHeight`).\nThe same applies to AE/AWB/AF regions and faces. This coordinate system change doesn't apply to\nRAW capture and its related metadata such as `intrinsicCalibration` and\n`lensShadingMap`.\n\nUsing the same hypothetical example above, and assuming output stream #1 (640x480) is the\nviewfinder stream, 2.0x zoom can be achieved in one of two ways:\n\n- `zoomRatio = 2.0`, `scaler.cropRegion = (0, 0, 2000, 1500)`\n- `zoomRatio = 1.0` (default), `scaler.cropRegion = (500, 375, 1000, 750)`\n\nFor an app to set `android.control.aeRegions` to be the top-left\nquarter of the viewfinder field of view, set\n`android.control.aeRegions` to `(0, 0, 1000, 750)` with\n`android.control.zoomRatio` set to `2.0`. Alternatively,\nthe app can set `android.control.aeRegions` to the equivalent\nregion of `(500, 375, 1000, 750)` for\n`android.control.zoomRatio` of `1.0`."]]
