camera/camera-core/src/main/java/androidx/camera/core/ImageAnalysis.java - platform/frameworks/support - Git at Google

 /*
  * Copyright (C) 2019 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package androidx.camera.core;

 import static androidx.camera.core.impl.ImageAnalysisConfig.OPTION_BACKPRESSURE_STRATEGY;
 import static androidx.camera.core.impl.ImageAnalysisConfig.OPTION_IMAGE_QUEUE_DEPTH;
 import static androidx.camera.core.impl.ImageAnalysisConfig.OPTION_IMAGE_READER_PROXY_PROVIDER;
 import static androidx.camera.core.impl.ImageOutputConfig.OPTION_MAX_RESOLUTION;
 import static androidx.camera.core.impl.ImageOutputConfig.OPTION_SUPPORTED_RESOLUTIONS;
 import static androidx.camera.core.impl.ImageOutputConfig.OPTION_TARGET_ASPECT_RATIO;
 import static androidx.camera.core.impl.ImageOutputConfig.OPTION_TARGET_ASPECT_RATIO_CUSTOM;
 import static androidx.camera.core.impl.ImageOutputConfig.OPTION_TARGET_RESOLUTION;
 import static androidx.camera.core.impl.ImageOutputConfig.OPTION_TARGET_ROTATION;
 import static androidx.camera.core.impl.UseCaseConfig.OPTION_CAMERA_SELECTOR;
 import static androidx.camera.core.impl.UseCaseConfig.OPTION_CAPTURE_CONFIG_UNPACKER;
 import static androidx.camera.core.impl.UseCaseConfig.OPTION_DEFAULT_CAPTURE_CONFIG;
 import static androidx.camera.core.impl.UseCaseConfig.OPTION_DEFAULT_SESSION_CONFIG;
 import static androidx.camera.core.impl.UseCaseConfig.OPTION_SESSION_CONFIG_UNPACKER;
 import static androidx.camera.core.impl.UseCaseConfig.OPTION_SURFACE_OCCUPANCY_PRIORITY;
 import static androidx.camera.core.impl.UseCaseConfig.OPTION_TARGET_CLASS;
 import static androidx.camera.core.impl.UseCaseConfig.OPTION_TARGET_NAME;
 import static androidx.camera.core.impl.UseCaseConfig.OPTION_USE_CASE_EVENT_CALLBACK;
 import static androidx.camera.core.internal.ThreadConfig.OPTION_BACKGROUND_EXECUTOR;

 import android.media.ImageReader;
 import android.util.Log;
 import android.util.Pair;
 import android.util.Rational;
 import android.util.Size;
 import android.view.Display;
 import android.view.Surface;

 import androidx.annotation.GuardedBy;
 import androidx.annotation.IntDef;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.annotation.RestrictTo;
 import androidx.annotation.RestrictTo.Scope;
 import androidx.camera.core.impl.CameraInfoInternal;
 import androidx.camera.core.impl.CaptureConfig;
 import androidx.camera.core.impl.ConfigProvider;
 import androidx.camera.core.impl.DeferrableSurface;
 import androidx.camera.core.impl.ImageAnalysisConfig;
 import androidx.camera.core.impl.ImageOutputConfig;
 import androidx.camera.core.impl.ImageOutputConfig.RotationValue;
 import androidx.camera.core.impl.ImageReaderProxy;
 import androidx.camera.core.impl.ImmediateSurface;
 import androidx.camera.core.impl.MutableConfig;
 import androidx.camera.core.impl.MutableOptionsBundle;
 import androidx.camera.core.impl.OptionsBundle;
 import androidx.camera.core.impl.SessionConfig;
 import androidx.camera.core.impl.UseCaseConfig;
 import androidx.camera.core.impl.utils.Threads;
 import androidx.camera.core.impl.utils.executor.CameraXExecutors;
 import androidx.camera.core.internal.TargetConfig;
 import androidx.camera.core.internal.ThreadConfig;
 import androidx.camera.core.internal.utils.UseCaseConfigUtil;
 import androidx.core.util.Preconditions;

 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.util.List;
 import java.util.UUID;
 import java.util.concurrent.Executor;

 /**
  * A use case providing CPU accessible images for an app to perform image analysis on.
  *
  * <p>ImageAnalysis acquires images from the camera via an {@link ImageReader}. Each image
  * is provided to an {@link ImageAnalysis.Analyzer} function which can be implemented by application
  * code, where it can access image data for application analysis via an {@link ImageProxy}.
  *
  * <p>The application is responsible for calling {@link ImageProxy#close()} to close the image.
  * Failing to close the image will cause future images to be stalled or dropped depending on the
  * backpressure strategy.
  */
 public final class ImageAnalysis extends UseCase {

     /**
      * Only deliver the latest image to the analyzer, dropping images as they arrive.
      *
      * <p>This strategy ignores the value set by {@link Builder#setImageQueueDepth(int)}.
      * Only one image will be delivered for analysis at a time. If more images are produced
      * while that image is being analyzed, they will be dropped and not queued for delivery.
      * Once the image being analyzed is closed by calling {@link ImageProxy#close()}, the
      * next latest image will be delivered.
      *
      * <p>Internally this strategy may make use of an internal {@link Executor} to receive
      * and drop images from the producer. A performance-tuned executor will be created
      * internally unless one is explicitly provided by
      * {@link Builder#setBackgroundExecutor(Executor)}. In order to
      * ensure smooth operation of this backpressure strategy, any user supplied
      * {@link Executor} must be able to quickly respond to tasks posted to it, so setting
      * the executor manually should only be considered in advanced use cases.
      *
      * @see Builder#setBackgroundExecutor(Executor)
      */
     public static final int STRATEGY_KEEP_ONLY_LATEST = 0;
     /**
      * Block the producer from generating new images.
      *
      * <p>Once the producer has produced the number of images equal to the image queue depth,
      * and none have been closed, the producer will stop producing images. Note that images
      * may be queued internally and not be delivered to the analyzer until the last delivered
      * image has been closed with {@link ImageProxy#close()}. These internally queued images
      * will count towards the total number of images that the producer can provide at any one
      * time.
      *
      * <p>When the producer stops producing images, it may also stop producing images for
      * other use cases, such as {@link Preview}, so it is important for the analyzer to keep
      * up with frame rate, <i>on average</i>. Failure to keep up with frame rate may lead to
      * jank in the frame stream and a diminished user experience. If more time is needed for
      * analysis on <i>some</i> frames, consider increasing the image queue depth with
      * {@link Builder#setImageQueueDepth(int)}.
      *
      * @see Builder#setImageQueueDepth(int)
      */
     public static final int STRATEGY_BLOCK_PRODUCER = 1;

     /**
      * Provides a static configuration with implementation-agnostic options.
      *
      * @hide
      */
     @RestrictTo(Scope.LIBRARY_GROUP)
     public static final Defaults DEFAULT_CONFIG = new Defaults();
     private static final String TAG = "ImageAnalysis";
     // ImageReader depth for KEEP_ONLY_LATEST mode.
     private static final int NON_BLOCKING_IMAGE_DEPTH = 4;

     @SuppressWarnings("WeakerAccess") /* synthetic access */
     final ImageAnalysisAbstractAnalyzer mImageAnalysisAbstractAnalyzer;
     @GuardedBy("mAnalysisLock")
     private ImageAnalysis.Analyzer mSubscribedAnalyzer;

     @Nullable
     private DeferrableSurface mDeferrableSurface;

     private final Object mAnalysisLock = new Object();

     /**
      * Creates a new image analysis use case from the given configuration.
      *
      * @param config for this use case instance
      */
     @SuppressWarnings("WeakerAccess")
     ImageAnalysis(@NonNull ImageAnalysisConfig config) {
         super(config);

         // Get the combined configuration with defaults
         ImageAnalysisConfig combinedConfig = (ImageAnalysisConfig) getUseCaseConfig();

         if (combinedConfig.getBackpressureStrategy() == STRATEGY_BLOCK_PRODUCER) {
             mImageAnalysisAbstractAnalyzer = new ImageAnalysisBlockingAnalyzer();
         } else {
             mImageAnalysisAbstractAnalyzer = new ImageAnalysisNonBlockingAnalyzer(
                     config.getBackgroundExecutor(CameraXExecutors.highPriorityExecutor()));
         }
     }

     @SuppressWarnings("WeakerAccess") /* synthetic accessor */
     SessionConfig.Builder createPipeline(@NonNull String cameraId,
             @NonNull ImageAnalysisConfig config, @NonNull Size resolution) {
         Threads.checkMainThread();

         Executor backgroundExecutor = Preconditions.checkNotNull(config.getBackgroundExecutor(
                 CameraXExecutors.highPriorityExecutor()));

         int imageQueueDepth =
                 config.getBackpressureStrategy() == STRATEGY_BLOCK_PRODUCER
                         ? config.getImageQueueDepth() : NON_BLOCKING_IMAGE_DEPTH;
         ImageReaderProxy imageReaderProxy;
         if (config.getImageReaderProxyProvider() != null) {
             imageReaderProxy = config.getImageReaderProxyProvider().newInstance(
                     resolution.getWidth(), resolution.getHeight(), getImageFormat(),
                     imageQueueDepth, 0);
         } else {
             imageReaderProxy = ImageReaderProxys.createIsolatedReader(
                     resolution.getWidth(),
                     resolution.getHeight(),
                     getImageFormat(),
                     imageQueueDepth);
         }

         tryUpdateRelativeRotation();

         mImageAnalysisAbstractAnalyzer.open();
         imageReaderProxy.setOnImageAvailableListener(mImageAnalysisAbstractAnalyzer,
                 backgroundExecutor);

         SessionConfig.Builder sessionConfigBuilder = SessionConfig.Builder.createFrom(config);

         if (mDeferrableSurface != null) {
             mDeferrableSurface.close();
         }
         mDeferrableSurface = new ImmediateSurface(imageReaderProxy.getSurface());
         mDeferrableSurface.getTerminationFuture().addListener(imageReaderProxy::close,
                 CameraXExecutors.mainThreadExecutor());

         sessionConfigBuilder.addSurface(mDeferrableSurface);

         sessionConfigBuilder.addErrorListener(new SessionConfig.ErrorListener() {
             @Override
             public void onError(@NonNull SessionConfig sessionConfig,
                     @NonNull SessionConfig.SessionError error) {
                 clearPipeline();

                 // Ensure the attached camera has not changed before resetting.
                 // TODO(b/143915543): Ensure this never gets called by a camera that is not attached
                 //  to this use case so we don't need to do this check.
                 if (isCurrentCamera(cameraId)) {
                     // Only reset the pipeline when the bound camera is the same.
                     SessionConfig.Builder sessionConfigBuilder = createPipeline(cameraId, config,
                             resolution);
                     updateSessionConfig(sessionConfigBuilder.build());

                     notifyReset();
                 }
             }
         });

         return sessionConfigBuilder;
     }

     /**
      * Clear the internal pipeline so that the pipeline can be set up again.
      */
     @SuppressWarnings("WeakerAccess") /* synthetic accessor */
     void clearPipeline() {
         Threads.checkMainThread();
         mImageAnalysisAbstractAnalyzer.close();

         if (mDeferrableSurface != null) {
             mDeferrableSurface.close();
             mDeferrableSurface = null;
         }
     }

     /**
      * Removes a previously set analyzer.
      *
      * <p>This will stop data from streaming to the {@link ImageAnalysis}.
      */
     public void clearAnalyzer() {
         synchronized (mAnalysisLock) {
             mImageAnalysisAbstractAnalyzer.setAnalyzer(null, null);
             mImageAnalysisAbstractAnalyzer.close();
             if (mSubscribedAnalyzer != null) {
                 notifyInactive();
             }
             mSubscribedAnalyzer = null;
         }
     }

     /**
      * Sets the target rotation.
      *
      * <p>This adjust the {@link ImageInfo#getRotationDegrees()} of the {@link ImageProxy} passed
      * to {@link Analyzer#analyze(ImageProxy)}. The rotation value of ImageInfo will be the
      * rotation, which if applied to the output image, will make the image match target rotation
      * specified here.
      *
      * <p>While rotation can also be set via {@link Builder#setTargetRotation(int)}, using
      * {@link ImageAnalysis#setTargetRotation(int)} allows the target rotation to be set
      * dynamically.
      *
      * <p>In general, it is best to use an {@link android.view.OrientationEventListener} to
      * set the target rotation.  This way, the rotation output to the Analyzer will indicate
      * which way is down for a given image.  This is important since display orientation may be
      * locked by device default, user setting, or app configuration, and some devices may not
      * transition to a reverse-portrait display orientation.  In these cases, use
      * {@link ImageAnalysis#setTargetRotation} to set target rotation dynamically according to
      * the {@link android.view.OrientationEventListener}, without re-creating the use case. Note
      * the OrientationEventListener output of degrees in the range [0..359] should be converted to
      * a surface rotation, i.e. one of {@link Surface#ROTATION_0}, {@link Surface#ROTATION_90},
      * {@link Surface#ROTATION_180}, or {@link Surface#ROTATION_270}.
      *
      * <p>When this function is called, value set by
      * {@link ImageAnalysis.Builder#setTargetResolution(Size)} will be updated automatically to
      * make sure the suitable resolution can be selected when the use case is bound.
      *
      * <p>If not set here or by configuration, the target rotation will default to the value of
      * {@link Display#getRotation()} of the default display at the time the
      * use case is created.
      *
      * @param rotation Target rotation of the output image, expressed as one of
      *                 {@link Surface#ROTATION_0}, {@link Surface#ROTATION_90},
      *                 {@link Surface#ROTATION_180}, or {@link Surface#ROTATION_270}.
      */
     public void setTargetRotation(@RotationValue int rotation) {
         ImageAnalysisConfig oldConfig = (ImageAnalysisConfig) getUseCaseConfig();
         Builder builder = Builder.fromConfig(oldConfig);
         int oldRotation = oldConfig.getTargetRotation(ImageOutputConfig.INVALID_ROTATION);
         if (oldRotation == ImageOutputConfig.INVALID_ROTATION || oldRotation != rotation) {
             UseCaseConfigUtil.updateTargetRotationAndRelatedConfigs(builder, rotation);
             updateUseCaseConfig(builder.getUseCaseConfig());

             // TODO(b/122846516): Update session configuration and possibly reconfigure session.
             // For now we'll just update the relative rotation value.
             // Attempt to get the camera ID and update the relative rotation. If we can't, we
             // probably
             // don't yet have permission, so we will try again in onSuggestedResolutionUpdated().
             // Old
             // configuration lens facing should match new configuration.
             try {
                 tryUpdateRelativeRotation();
             } catch (Exception e) {
                 // Likely don't yet have permissions. This is expected if this method is called
                 // before
                 // this use case becomes active. That's OK though since we've updated the use case
                 // configuration. We'll try to update relative rotation again in
                 // onSuggestedResolutionUpdated().
                 Log.w(TAG, "Unable to get camera id for the use case.");
             }
         }
     }

     /**
      * Returns the rotation of the intended target for images.
      *
      * <p>
      * The rotation can be set when constructing an {@link ImageAnalysis} instance using
      * {@link ImageAnalysis.Builder#setTargetRotation(int)}, or dynamically by calling
      * {@link ImageAnalysis#setTargetRotation(int)}. If not set, the target rotation defaults to
      * the value of {@link Display#getRotation()} of the default display at the time the use case
      * is created.
      * </p>
      *
      * @return The rotation of the intended target for images.
      * @see ImageAnalysis#setTargetRotation(int)
      */
     @RotationValue
     public int getTargetRotation() {
         return ((ImageAnalysisConfig) getUseCaseConfig()).getTargetRotation();
     }

     /**
      * Sets an analyzer to receive and analyze images.
      *
      * <p>Setting an analyzer will signal to the camera that it should begin sending data. The
      * stream of data can be stopped by calling {@link #clearAnalyzer()}.
      *
      * <p>Applications can process or copy the image by implementing the {@link Analyzer}.  If
      * frames should be skipped (no analysis), the analyzer function should return, instead of
      * disconnecting the analyzer function completely.
      *
      * <p>Setting an analyzer function replaces any previous analyzer.  Only one analyzer can be
      * set at any time.
      *
      * @param executor The executor in which the
      *                 {@link ImageAnalysis.Analyzer#analyze(ImageProxy)} will be run.
      * @param analyzer of the images.
      */
     public void setAnalyzer(@NonNull Executor executor, @NonNull Analyzer analyzer) {
         synchronized (mAnalysisLock) {
             mImageAnalysisAbstractAnalyzer.open();
             mImageAnalysisAbstractAnalyzer.setAnalyzer(executor, image -> {
                 if (getViewPortCropRect() != null) {
                     image.setViewPortRect(getViewPortCropRect());
                     image.setCropRect(getViewPortCropRect());
                 }
                 analyzer.analyze(image);
             });
             if (mSubscribedAnalyzer == null) {
                 notifyActive();
             }
             mSubscribedAnalyzer = analyzer;
         }
     }

     /**
      * Returns the mode with which images are acquired from the {@linkplain ImageReader image
      * producer}.
      *
      * <p>
      * The backpressure strategy is set when constructing an {@link ImageAnalysis} instance using
      * {@link ImageAnalysis.Builder#setBackpressureStrategy(int)}. If not set, it defaults to
      * {@link ImageAnalysis#STRATEGY_KEEP_ONLY_LATEST}.
      * </p>
      *
      * @return The backpressure strategy applied to the image producer.
      * @see ImageAnalysis.Builder#setBackpressureStrategy(int)
      */
     @BackpressureStrategy
     public int getBackpressureStrategy() {
         return ((ImageAnalysisConfig) getUseCaseConfig()).getBackpressureStrategy();
     }

     /**
      * Returns the number of images available to the camera pipeline, including the image being
      * analyzed, for the {@link #STRATEGY_BLOCK_PRODUCER} backpressure mode.
      *
      * <p>
      * The image queue depth is set when constructing an {@link ImageAnalysis} instance using
      * {@link ImageAnalysis.Builder#setImageQueueDepth(int)}. If not set, and this option is used
      * by the backpressure strategy, the default will be a queue depth of 6 images.
      * </p>
      *
      * @return The image queue depth for the {@link #STRATEGY_BLOCK_PRODUCER} backpressure mode.
      * @see ImageAnalysis.Builder#setImageQueueDepth(int)
      * @see ImageAnalysis.Builder#setBackpressureStrategy(int)
      */
     public int getImageQueueDepth() {
         return ((ImageAnalysisConfig) getUseCaseConfig()).getImageQueueDepth();
     }

     @Override
     @NonNull
     public String toString() {
         return TAG + ":" + getName();
     }

     /**
      * {@inheritDoc}
      *
      * @hide
      */
     @RestrictTo(Scope.LIBRARY_GROUP)
     @Override
     public void clear() {
         clearPipeline();
     }

     /**
      * {@inheritDoc}
      *
      * @hide
      */
     @RestrictTo(Scope.LIBRARY_GROUP)
     @Override
     public void onDestroy() {
         clearAnalyzer();
     }

     /**
      * {@inheritDoc}
      *
      * @hide
      */
     @Override
     @Nullable
     @RestrictTo(Scope.LIBRARY_GROUP)
     protected UseCaseConfig.Builder<?, ?, ?> getDefaultBuilder(@Nullable CameraInfo cameraInfo) {
         ImageAnalysisConfig defaults = CameraX.getDefaultUseCaseConfig(ImageAnalysisConfig.class,
                 cameraInfo);
         if (defaults != null) {
             return Builder.fromConfig(defaults);
         }

         return null;
     }

     /**
      * {@inheritDoc}
      *
      * @hide
      */
     @Override
     @RestrictTo(Scope.LIBRARY_GROUP)
     @NonNull
     protected Size onSuggestedResolutionUpdated(@NonNull Size suggestedResolution) {
         final ImageAnalysisConfig config = (ImageAnalysisConfig) getUseCaseConfig();

         SessionConfig.Builder sessionConfigBuilder = createPipeline(getCameraId(), config,
                 suggestedResolution);
         updateSessionConfig(sessionConfigBuilder.build());

         return suggestedResolution;
     }

     private void tryUpdateRelativeRotation() {
         ImageOutputConfig config = (ImageOutputConfig) getUseCaseConfig();
         CameraInfoInternal cameraInfoInternal = getCamera().getCameraInfoInternal();
         mImageAnalysisAbstractAnalyzer.setRelativeRotation(
                 cameraInfoInternal.getSensorRotationDegrees(
                         config.getTargetRotation(Surface.ROTATION_0)));
     }

     /**
      * How to apply backpressure to the source producing images for analysis.
      *
      * <p>Sometimes, images may be produced faster than they can be analyzed. Since images
      * generally reserve a large portion of the device's memory, they cannot be buffered
      * unbounded and indefinitely. The backpressure strategy defines how to deal with this scenario.
      *
      * <p>The receiver of the {@link ImageProxy} is responsible for explicitly closing the image
      * by calling {@link ImageProxy#close()}. However, the image will only be valid when the
      * ImageAnalysis instance is bound to a camera.
      *
      * @hide
      * @see Builder#setBackpressureStrategy(int)
      */
     @IntDef({STRATEGY_KEEP_ONLY_LATEST, STRATEGY_BLOCK_PRODUCER})
     @Retention(RetentionPolicy.SOURCE)
     @RestrictTo(Scope.LIBRARY_GROUP)
     public @interface BackpressureStrategy {
     }

     /**
      * Interface for analyzing images.
      *
      * <p>Implement Analyzer and pass it to {@link ImageAnalysis#setAnalyzer(Executor, Analyzer)}
      * to receive images and perform custom processing by implementing the
      * {@link ImageAnalysis.Analyzer#analyze(ImageProxy)} function.
      */
     public interface Analyzer {
         /**
          * Analyzes an image to produce a result.
          *
          * <p>This method is called once for each image from the camera, and called at the
          * frame rate of the camera. Each analyze call is executed sequentially.
          *
          * <p>It is the responsibility of the application to close the image once done with it.
          * If the images are not closed then it may block further images from being produced
          * (causing the preview to stall) or drop images as determined by the configured
          * backpressure strategy. The exact behavior is configurable via
          * {@link ImageAnalysis.Builder#setBackpressureStrategy(int)}.
          *
          * <p>Images produced here will no longer be valid after the {@link ImageAnalysis}
          * instance that produced it has been unbound from the camera.
          *
          * <p>The image provided has format {@link android.graphics.ImageFormat#YUV_420_888}.
          *
          * <p>The provided image is typically in the orientation of the sensor, meaning CameraX
          * does not perform an internal rotation of the data.  The rotationDegrees parameter allows
          * the analysis to understand the image orientation when processing or to apply a rotation.
          * For example, if the
          * {@linkplain ImageAnalysis#setTargetRotation(int) target rotation}) is natural
          * orientation, rotationDegrees would be the rotation which would align the buffer
          * data ordering to natural orientation.
          *
          * <p>Timestamps are in nanoseconds and monotonic and can be compared to timestamps from
          * images produced from UseCases bound to the same camera instance.  More detail is
          * available depending on the implementation.  For example with CameraX using a
          * {@link androidx.camera.camera2} implementation additional detail can be found in
          * {@link android.hardware.camera2.CameraDevice} documentation.
          *
          * @param image The image to analyze
          * @see android.media.Image#getTimestamp()
          * @see android.hardware.camera2.CaptureResult#SENSOR_TIMESTAMP
          */
         void analyze(@NonNull ImageProxy image);
     }

     /**
      * Provides a base static default configuration for the ImageAnalysis.
      *
      * <p>These values may be overridden by the implementation. They only provide a minimum set of
      * defaults that are implementation independent.
      *
      * @hide
      */
     @RestrictTo(Scope.LIBRARY_GROUP)
     public static final class Defaults implements ConfigProvider<ImageAnalysisConfig> {
         @BackpressureStrategy
         private static final int DEFAULT_BACKPRESSURE_STRATEGY = STRATEGY_KEEP_ONLY_LATEST;
         private static final int DEFAULT_IMAGE_QUEUE_DEPTH = 6;
         private static final Size DEFAULT_TARGET_RESOLUTION = new Size(640, 480);
         private static final Size DEFAULT_MAX_RESOLUTION = new Size(1920, 1080);
         private static final int DEFAULT_SURFACE_OCCUPANCY_PRIORITY = 1;

         private static final ImageAnalysisConfig DEFAULT_CONFIG;

         static {
             Builder builder = new Builder()
                     .setBackpressureStrategy(DEFAULT_BACKPRESSURE_STRATEGY)
                     .setImageQueueDepth(DEFAULT_IMAGE_QUEUE_DEPTH)
                     .setDefaultResolution(DEFAULT_TARGET_RESOLUTION)
                     .setMaxResolution(DEFAULT_MAX_RESOLUTION)
                     .setSurfaceOccupancyPriority(DEFAULT_SURFACE_OCCUPANCY_PRIORITY);

             DEFAULT_CONFIG = builder.getUseCaseConfig();
         }

         @NonNull
         @Override
         public ImageAnalysisConfig getConfig(@Nullable CameraInfo cameraInfo) {
             return DEFAULT_CONFIG;
         }
     }

     /** Builder for a {@link ImageAnalysis}. */
     public static final class Builder
             implements ImageOutputConfig.Builder<Builder>,
             ThreadConfig.Builder<Builder>,
             UseCaseConfig.Builder<ImageAnalysis, ImageAnalysisConfig, Builder> {

         private final MutableOptionsBundle mMutableConfig;

         /** Creates a new Builder object. */
         public Builder() {
             this(MutableOptionsBundle.create());
         }

         private Builder(MutableOptionsBundle mutableConfig) {
             mMutableConfig = mutableConfig;

             Class<?> oldConfigClass =
                     mutableConfig.retrieveOption(TargetConfig.OPTION_TARGET_CLASS, null);
             if (oldConfigClass != null && !oldConfigClass.equals(ImageAnalysis.class)) {
                 throw new IllegalArgumentException(
                         "Invalid target class configuration for "
                                 + Builder.this
                                 + ": "
                                 + oldConfigClass);
             }

             setTargetClass(ImageAnalysis.class);
         }

         /**
          * Generates a Builder from another Config object.
          *
          * @param configuration An immutable configuration to pre-populate this builder.
          * @return The new Builder.
          * @hide
          */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @NonNull
         public static Builder fromConfig(@NonNull ImageAnalysisConfig configuration) {
             return new Builder(MutableOptionsBundle.from(configuration));
         }

         /**
          * Sets the backpressure strategy to apply to the image producer to deal with scenarios
          * where images may be produced faster than they can be analyzed.
          *
          * <p>The available values are {@link #STRATEGY_BLOCK_PRODUCER} and
          * {@link #STRATEGY_KEEP_ONLY_LATEST}.
          *
          * <p>If not set, the backpressure strategy will default to
          * {@link #STRATEGY_KEEP_ONLY_LATEST}.
          *
          * @param strategy The strategy to use.
          * @return The current Builder.
          */
         @NonNull
         public Builder setBackpressureStrategy(@BackpressureStrategy int strategy) {
             getMutableConfig().insertOption(OPTION_BACKPRESSURE_STRATEGY, strategy);
             return this;
         }

         /**
          * Sets the number of images available to the camera pipeline for
          * {@link #STRATEGY_BLOCK_PRODUCER} mode.
          *
          * <p>The image queue depth is the number of images available to the camera to fill with
          * data. This includes the image currently being analyzed by {@link
          * ImageAnalysis.Analyzer#analyze(ImageProxy)}. Increasing the image queue depth
          * may make camera operation smoother, depending on the backpressure strategy, at
          * the cost of increased memory usage.
          *
          * <p>When the backpressure strategy is set to {@link #STRATEGY_BLOCK_PRODUCER},
          * increasing the image queue depth may make the camera pipeline run smoother on systems
          * under high load. However, the time spent analyzing an image should still be kept under
          * a single frame period for the current frame rate, <i>on average</i>, to avoid stalling
          * the camera pipeline.
          *
          * <p>The value only applies to {@link #STRATEGY_BLOCK_PRODUCER} mode.
          * For {@link #STRATEGY_KEEP_ONLY_LATEST} the value is ignored.
          *
          * <p>If not set, and this option is used by the selected backpressure strategy,
          * the default will be a queue depth of 6 images.
          *
          * @param depth The total number of images available to the camera.
          * @return The current Builder.
          */
         @NonNull
         public Builder setImageQueueDepth(int depth) {
             getMutableConfig().insertOption(OPTION_IMAGE_QUEUE_DEPTH, depth);
             return this;
         }

         /**
          * {@inheritDoc}
          *
          * @hide
          */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         @NonNull
         public MutableConfig getMutableConfig() {
             return mMutableConfig;
         }

         /**
          * {@inheritDoc}
          *
          * @hide
          */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @NonNull
         @Override
         public ImageAnalysisConfig getUseCaseConfig() {
             return new ImageAnalysisConfig(OptionsBundle.from(mMutableConfig));
         }

         /**
          * Builds an {@link ImageAnalysis} from the current state.
          *
          * @return A {@link ImageAnalysis} populated with the current state.
          * @throws IllegalArgumentException if attempting to set both target aspect ratio and
          *                                  target resolution.
          */
         @Override
         @NonNull
         public ImageAnalysis build() {
             // Error at runtime for using both setTargetResolution and setTargetAspectRatio on
             // the same config.
             if (getMutableConfig().retrieveOption(OPTION_TARGET_ASPECT_RATIO, null) != null
                     && getMutableConfig().retrieveOption(OPTION_TARGET_RESOLUTION, null) != null) {
                 throw new IllegalArgumentException(
                         "Cannot use both setTargetResolution and setTargetAspectRatio on the same"
                                 + " config.");
             }
             return new ImageAnalysis(getUseCaseConfig());
         }

         // Implementations of TargetConfig.Builder default methods

         /** @hide */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         @NonNull
         public Builder setTargetClass(@NonNull Class<ImageAnalysis> targetClass) {
             getMutableConfig().insertOption(OPTION_TARGET_CLASS, targetClass);

             // If no name is set yet, then generate a unique name
             if (null == getMutableConfig().retrieveOption(OPTION_TARGET_NAME, null)) {
                 String targetName = targetClass.getCanonicalName() + "-" + UUID.randomUUID();
                 setTargetName(targetName);
             }

             return this;
         }

         /**
          * Sets the name of the target object being configured, used only for debug logging.
          *
          * <p>The name should be a value that can uniquely identify an instance of the object being
          * configured.
          *
          * <p>If not set, the target name will default to a unique name automatically generated
          * with the class canonical name and random UUID.
          *
          * @param targetName A unique string identifier for the instance of the class being
          *                   configured.
          * @return the current Builder.
          */
         @Override
         @NonNull
         public Builder setTargetName(@NonNull String targetName) {
             getMutableConfig().insertOption(OPTION_TARGET_NAME, targetName);
             return this;
         }

         // Implementations of ImageOutputConfig.Builder default methods

         /**
          * Sets the aspect ratio of the intended target for images from this configuration.
          *
          * <p>This is the ratio of the target's width to the image's height, where the numerator of
          * the provided {@link Rational} corresponds to the width, and the denominator corresponds
          * to the height.
          *
          * <p>The target aspect ratio is used as a hint when determining the resulting output aspect
          * ratio which may differ from the request, possibly due to device constraints.
          * Application code should check the resulting output's resolution.
          *
          * <p>This method can be used to request an aspect ratio that is not from the standard set
          * of aspect ratios defined in the {@link AspectRatio}.
          *
          * <p>This method will remove any value set by setTargetAspectRatio().
          *
          * <p>For ImageAnalysis, the output is the {@link ImageProxy} passed to the analyzer
          * function.
          *
          * @param aspectRatio A {@link Rational} representing the ratio of the target's width and
          *                    height.
          * @return The current Builder.
          * @hide
          */
         @NonNull
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         public Builder setTargetAspectRatioCustom(@NonNull Rational aspectRatio) {
             getMutableConfig().insertOption(OPTION_TARGET_ASPECT_RATIO_CUSTOM, aspectRatio);
             getMutableConfig().removeOption(OPTION_TARGET_ASPECT_RATIO);
             return this;
         }

         /**
          * Sets the aspect ratio of the intended target for images from this configuration.
          *
          * <p>The aspect ratio is the ratio of width to height in the sensor orientation.
          *
          * <p>It is not allowed to set both target aspect ratio and target resolution on the same
          * use case.  Attempting so will throw an IllegalArgumentException when building the
          * Config.
          *
          * <p>The target aspect ratio is used as a hint when determining the resulting output aspect
          * ratio which may differ from the request, possibly due to device constraints.
          * Application code should check the resulting output's resolution.
          *
          * <p>If not set, resolutions with aspect ratio 4:3 will be considered in higher
          * priority.
          *
          * @param aspectRatio The desired ImageAnalysis {@link AspectRatio}
          * @return The current Builder.
          */
         @NonNull
         @Override
         public Builder setTargetAspectRatio(@AspectRatio.Ratio int aspectRatio) {
             getMutableConfig().insertOption(OPTION_TARGET_ASPECT_RATIO, aspectRatio);
             return this;
         }

         /**
          * Sets the rotation of the intended target for images from this configuration.
          *
          * <p>This adjust the {@link ImageInfo#getRotationDegrees()} of the {@link ImageProxy}
          * passed to {@link Analyzer#analyze(ImageProxy)}. The rotation value of ImageInfo will
          * be the rotation, which if applied to the output image, will make the image match
          * target rotation specified here.
          *
          * <p>This is one of four valid values: {@link Surface#ROTATION_0}, {@link
          * Surface#ROTATION_90}, {@link Surface#ROTATION_180}, {@link Surface#ROTATION_270}.
          * Rotation values are relative to the "natural" rotation, {@link Surface#ROTATION_0}.
          *
          * <p>In general, it is best to additionally set the target rotation dynamically on the use
          * case.  See
          * {@link androidx.camera.core.ImageAnalysis#setTargetRotation(int)} for additional
          * documentation.
          *
          * <p>If not set, the target rotation will default to the value of
          * {@link android.view.Display#getRotation()} of the default display at the time the
          * use case is created.
          *
          * @param rotation The rotation of the intended target.
          * @return The current Builder.
          * @see androidx.camera.core.ImageAnalysis#setTargetRotation(int)
          * @see android.view.OrientationEventListener
          */
         @NonNull
         @Override
         public Builder setTargetRotation(@RotationValue int rotation) {
             getMutableConfig().insertOption(OPTION_TARGET_ROTATION, rotation);
             return this;
         }

         /**
          * Sets the resolution of the intended target from this configuration.
          *
          * <p>The target resolution attempts to establish a minimum bound for the image resolution.
          * The actual image resolution will be the closest available resolution in size that is not
          * smaller than the target resolution, as determined by the Camera implementation. However,
          * if no resolution exists that is equal to or larger than the target resolution, the
          * nearest available resolution smaller than the target resolution will be chosen.
          * Resolutions with the same aspect ratio of the provided {@link Size} will be considered in
          * higher priority before resolutions of different aspect ratios.
          *
          * <p>It is not allowed to set both target aspect ratio and target resolution on the same
          * use case.  Attempting so will throw an IllegalArgumentException when building the
          * Config.
          *
          * <p>The resolution {@link Size} should be expressed at the use cases's target rotation.
          * For example, a device with portrait natural orientation in natural target rotation
          * requesting a portrait image may specify 480x640, and the same device, rotated 90 degrees
          * and targeting landscape orientation may specify 640x480.
          *
          * <p>The maximum available resolution that could be selected for an {@link ImageAnalysis}
          * is limited to be under 1080p. The limitation of 1080p for {@link ImageAnalysis} has
          * considered both performance and quality factors so that users can obtain reasonable
          * quality and smooth output stream under 1080p.
          *
          * <p>If not set, resolution of 640x480 will be selected to use in priority.
          *
          * @param resolution The target resolution to choose from supported output sizes list.
          * @return The current Builder.
          */
         @NonNull
         @Override
         public Builder setTargetResolution(@NonNull Size resolution) {
             getMutableConfig()
                     .insertOption(ImageOutputConfig.OPTION_TARGET_RESOLUTION, resolution);
             getMutableConfig().insertOption(OPTION_TARGET_ASPECT_RATIO_CUSTOM,
                     new Rational(resolution.getWidth(), resolution.getHeight()));
             return this;
         }

         /**
          * Sets the default resolution of the intended target from this configuration.
          *
          * @param resolution The default resolution to choose from supported output sizes list.
          * @return The current Builder.
          * @hide
          */
         @NonNull
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         public Builder setDefaultResolution(@NonNull Size resolution) {
             getMutableConfig().insertOption(ImageOutputConfig.OPTION_DEFAULT_RESOLUTION,
                     resolution);
             return this;
         }

         /** @hide */
         @NonNull
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         public Builder setMaxResolution(@NonNull Size resolution) {
             getMutableConfig().insertOption(OPTION_MAX_RESOLUTION, resolution);
             return this;
         }

         /** @hide */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         @NonNull
         public Builder setSupportedResolutions(@NonNull List<Pair<Integer, Size[]>> resolutions) {
             getMutableConfig().insertOption(OPTION_SUPPORTED_RESOLUTIONS, resolutions);
             return this;
         }

         // Implementations of ThreadConfig.Builder default methods

         /**
          * Sets the default executor that will be used for background tasks.
          *
          * <p>If not set, the background executor will default to an automatically generated
          * {@link Executor}.
          *
          * @param executor The executor which will be used for background tasks.
          * @return the current Builder.
          */
         @Override
         @NonNull
         public Builder setBackgroundExecutor(@NonNull Executor executor) {
             getMutableConfig().insertOption(OPTION_BACKGROUND_EXECUTOR, executor);
             return this;
         }

         // Implementations of UseCaseConfig.Builder default methods

         /** @hide */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         @NonNull
         public Builder setDefaultSessionConfig(@NonNull SessionConfig sessionConfig) {
             getMutableConfig().insertOption(OPTION_DEFAULT_SESSION_CONFIG, sessionConfig);
             return this;
         }

         /** @hide */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         @NonNull
         public Builder setDefaultCaptureConfig(@NonNull CaptureConfig captureConfig) {
             getMutableConfig().insertOption(OPTION_DEFAULT_CAPTURE_CONFIG, captureConfig);
             return this;
         }

         /** @hide */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         @NonNull
         public Builder setSessionOptionUnpacker(
                 @NonNull SessionConfig.OptionUnpacker optionUnpacker) {
             getMutableConfig().insertOption(OPTION_SESSION_CONFIG_UNPACKER, optionUnpacker);
             return this;
         }

         /** @hide */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         @NonNull
         public Builder setCaptureOptionUnpacker(
                 @NonNull CaptureConfig.OptionUnpacker optionUnpacker) {
             getMutableConfig().insertOption(OPTION_CAPTURE_CONFIG_UNPACKER, optionUnpacker);
             return this;
         }

         /** @hide */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         @NonNull
         public Builder setSurfaceOccupancyPriority(int priority) {
             getMutableConfig().insertOption(OPTION_SURFACE_OCCUPANCY_PRIORITY, priority);
             return this;
         }

         /** @hide */
         @RestrictTo(Scope.LIBRARY)
         @Override
         @NonNull
         public Builder setCameraSelector(@NonNull CameraSelector cameraSelector) {
             getMutableConfig().insertOption(OPTION_CAMERA_SELECTOR, cameraSelector);
             return this;
         }

         /** @hide */
         @RestrictTo(Scope.LIBRARY_GROUP)
         @Override
         @NonNull
         public Builder setUseCaseEventCallback(
                 @NonNull UseCase.EventCallback useCaseEventCallback) {
             getMutableConfig().insertOption(OPTION_USE_CASE_EVENT_CALLBACK, useCaseEventCallback);
             return this;
         }

         /** @hide */
         @NonNull
         @RestrictTo(Scope.LIBRARY_GROUP)
         public Builder setImageReaderProxyProvider(
                 @NonNull ImageReaderProxyProvider imageReaderProxyProvider) {
             getMutableConfig().insertOption(OPTION_IMAGE_READER_PROXY_PROVIDER,
                     imageReaderProxyProvider);
             return this;
         }
     }
 }