This is an automated email from the ASF dual-hosted git repository. mwalenia pushed a commit to branch BEAM-9147-videointelligence in repository https://gitbox.apache.org/repos/asf/beam.git
commit d1c23bf7b654d2561ae977fd43122559811af7b2 Author: Michal Walenia <[email protected]> AuthorDate: Mon Mar 30 12:12:20 2020 +0200 [BEAM-9147] Add documentation of VideoIntelligence transforms --- build.gradle | 3 +- .../beam/sdk/extensions/ml/AnnotateVideo.java | 16 +++++++ .../beam/sdk/extensions/ml/VideoIntelligence.java | 56 ++++++++++++++++++++++ 3 files changed, 74 insertions(+), 1 deletion(-) diff --git a/build.gradle b/build.gradle index 2a5d541..021ba5b 100644 --- a/build.gradle +++ b/build.gradle @@ -107,7 +107,8 @@ rat { "learning/katas/*/IO/**/*.txt", // Mockito extensions - "sdks/java/io/amazon-web-services2/src/test/resources/mockito-extensions/org.mockito.plugins.MockMaker" + "sdks/java/io/amazon-web-services2/src/test/resources/mockito-extensions/org.mockito.plugins.MockMaker", + "sdks/java/extensions/ml/src/test/resources/mockito-extensions/org.mockito.plugins.MockMaker" ] // Add .gitignore excludes to the Apache Rat exclusion list. We re-create the behavior diff --git a/sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/AnnotateVideo.java b/sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/AnnotateVideo.java index edb5c04..6e7de6f 100644 --- a/sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/AnnotateVideo.java +++ b/sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/AnnotateVideo.java @@ -27,6 +27,12 @@ import java.util.concurrent.ExecutionException; import org.apache.beam.sdk.transforms.DoFn; import org.apache.beam.sdk.values.PCollectionView; +/** + * Base class for Video Intelligence transform. + * + * @param <T> Class of input data being passed in - either ByteString - video data encoded into + * String or String - a GCS URI of the video to be annotated + */ public abstract class AnnotateVideo<T> extends DoFn<T, List<VideoAnnotationResults>> { protected final PCollectionView<Map<T, VideoContext>> contextSideInput; @@ -54,6 +60,15 @@ public abstract class AnnotateVideo<T> extends DoFn<T, List<VideoAnnotationResul videoIntelligenceServiceClient.close(); } + /** + * Call the Video Intelligence Cloud AI service and return annotation results + * + * @param elementURI This or elementContents is required. GCS address of video to be annotated + * @param elementContents this or elementURI is required. Hex-encoded contents of video to be + * annotated + * @param videoContext Optional context for video annotation. + * @return + */ List<VideoAnnotationResults> getVideoAnnotationResults( String elementURI, ByteString elementContents, VideoContext videoContext) throws InterruptedException, ExecutionException { @@ -75,6 +90,7 @@ public abstract class AnnotateVideo<T> extends DoFn<T, List<VideoAnnotationResul return annotateVideoAsync.get().getAnnotationResultsList(); } + /** Process element implementation required. */ @ProcessElement public abstract void processElement(ProcessContext context) throws ExecutionException, InterruptedException; diff --git a/sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/VideoIntelligence.java b/sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/VideoIntelligence.java index 4b01de0..267f65b 100644 --- a/sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/VideoIntelligence.java +++ b/sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/VideoIntelligence.java @@ -25,27 +25,67 @@ import java.util.concurrent.ExecutionException; import org.apache.beam.sdk.values.KV; import org.apache.beam.sdk.values.PCollectionView; +/** + * Factory class for AnnotateVideo subclasses. allows integration with Google Cloud AI - + * VideoIntelligence service. Converts GCS URIs of videos or ByteStrings with video contents into + * Lists of VideoAnnotationResults. + * + * <p>Adding a side input of Maps of elements to VideoContext objects is allowed, so is using KVs of + * element and VideoContext as input. + * + * <p>Service account with proper permissions is required to use these transforms. + */ public class VideoIntelligence { + /** + * Annotates videos from GCS URIs. + * + * @param featureList List of features to be annotated + * @param contextSideInput Optional side input with map of contexts to URIs + * @return DoFn performing the necessary operations + */ public static AnnotateVideoFromURI annotateFromURI( List<Feature> featureList, PCollectionView<Map<String, VideoContext>> contextSideInput) { return new AnnotateVideoFromURI(contextSideInput, featureList); } + /** + * Annotates videos from ByteStrings of their contents. + * + * @param featureList List of features to be annotated + * @param contextSideInput Optional side input with map of contexts to ByteStrings + * @return DoFn performing the necessary operations + */ public static AnnotateVideoFromBytes annotateFromBytes( PCollectionView<Map<ByteString, VideoContext>> contextSideInput, List<Feature> featureList) { return new AnnotateVideoFromBytes(contextSideInput, featureList); } + /** + * Annotates videos from key-value pairs of GCS URI and VideoContext + * + * @param featureList List of features to be annotated + * @return DoFn performing the necessary operations + */ public static AnnotateVideoURIWithContext annotateFromUriWithContext(List<Feature> featureList) { return new AnnotateVideoURIWithContext(featureList); } + /** + * Annotates videos from key-value pairs of ByteStrings and VideoContext + * + * @param featureList List of features to be annotated + * @return DoFn performing the necessary operations + */ public static AnnotateVideoBytesWithContext annotateFromBytesWithContext( List<Feature> featureList) { return new AnnotateVideoBytesWithContext(featureList); } + /** + * Implementation of AnnotateVideo accepting Strings as contents of input PCollection. Annotates + * videos found on GCS based on URIs from input PCollection + */ public static class AnnotateVideoFromURI extends AnnotateVideo<String> { public AnnotateVideoFromURI( @@ -53,6 +93,7 @@ public class VideoIntelligence { super(contextSideInput, featureList); } + /** ProcessElement implementation. */ @Override public void processElement(ProcessContext context) throws ExecutionException, InterruptedException { @@ -67,6 +108,10 @@ public class VideoIntelligence { } } + /** + * Implementation of AnnotateVideo accepting ByteStrings as contents of input PCollection. Videos + * decoded from the ByteStrings are annotated. + */ public static class AnnotateVideoFromBytes extends AnnotateVideo<ByteString> { public AnnotateVideoFromBytes( @@ -75,6 +120,7 @@ public class VideoIntelligence { super(contextSideInput, featureList); } + /** Implementation of ProcessElement */ @Override public void processElement(ProcessContext context) throws ExecutionException, InterruptedException { @@ -89,12 +135,17 @@ public class VideoIntelligence { } } + /** + * Implementation of AnnotateVideo accepting KVs as contents of input PCollection. Keys are the + * GCS URIs, values - VideoContext objects. + */ public static class AnnotateVideoURIWithContext extends AnnotateVideo<KV<String, VideoContext>> { public AnnotateVideoURIWithContext(List<Feature> featureList) { super(featureList); } + /** ProcessElement implementation */ @Override public void processElement(ProcessContext context) throws ExecutionException, InterruptedException { @@ -106,6 +157,10 @@ public class VideoIntelligence { } } + /** + * Implementation of AnnotateVideo accepting KVs as contents of input PCollection. Keys are the + * ByteString encoded video contents, values - VideoContext objects. + */ public static class AnnotateVideoBytesWithContext extends AnnotateVideo<KV<ByteString, VideoContext>> { @@ -113,6 +168,7 @@ public class VideoIntelligence { super(featureList); } + /** ProcessElement implementation */ @Override public void processElement(ProcessContext context) throws ExecutionException, InterruptedException {
