You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beam.apache.org by mw...@apache.org on 2020/03/30 10:17:30 UTC
[beam] 03/03: [BEAM-9147] Add documentation of VideoIntelligence
transforms
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 <mi...@polidea.com>
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 {