timesformer/README.md

# Action Classification with TimeSformer

*Author: [Jael Gu](https://github.com/jaelgu)*

<br />

## Description

An action classification operator generates labels of human activities (with corresponding scores)
and extracts features for the input video.
It transforms the video into frames and loads pre-trained models by model names.
This operator has implemented pre-trained models from [TimeSformer](https://arxiv.org/abs/2102.05095)
and maps vectors with labels.

<br />

## Code Example

Use the pretrained TimeSformer model ('timesformer_k400_8x224')
to classify and generate a vector for the given video path './archery.mp4' ([download](https://dl.fbaipublicfiles.com/pytorchvideo/projects/archery.mp4)).

*Write a pipeline with explicit inputs/outputs name specifications:*

```python
from towhee import pipe, ops, DataCollection

p = (
    pipe.input('path')
        .map('path', 'frames', ops.video_decode.ffmpeg())
        .map('frames', ('labels', 'scores', 'features'),
             ops.action_classification.timesformer(model_name='timesformer_k400_8x224'))
        .output('path', 'labels', 'scores', 'features')
)

DataCollection(p('./archery.mp4')).show()
```
<img src="./result.png" width="800px"/>

<br />

## Factory Constructor

Create the operator via the following factory method

***action_classification.timesformer(
model_name='timesformer_k400_8x224', skip_preprocess=False, classmap=None, topk=5)***

**Parameters:**

​	***model_name***: *str*

​	The name of pre-trained model. Supported model names:
- timesformer_k400_8x224

​	***skip_preprocess***: *bool*

​	Flag to control whether to skip UniformTemporalSubsample in video transforms, defaults to False.
If set to True, the step of UniformTemporalSubsample will be skipped.
In this case, the user should guarantee that all the input video frames are already reprocessed properly,
and thus can be fed to model directly.

​	***classmap***: *Dict[str: int]*: 

​	Dictionary that maps class names to one hot vectors.
If not given, the operator will load the default class map dictionary.

​	***topk***: *int*

​	The topk labels & scores to present in result. The default value is 5.

## Interface

A video classification operator generates a list of class labels
and a corresponding vector in numpy.ndarray given a video input data.

**Parameters:**

​	***video***: *List[towhee.types.VideoFrame]*

​	Input video data should be a list of towhee.types.VideoFrame representing video frames in order.


**Returns**:

​   ***labels, scores, features***: *Tuple(List[str], List[float], numpy.ndarray)*

- labels: predicted class names.
- scores: possibility scores ranking from high to low corresponding to predicted labels.
- features: a video embedding in shape of (768,) representing features extracted by model.




# More Resources

- [Understanding Class Activation Mapping (CAM) in Deep Learning - Zilliz blog](https://zilliz.com/learn/class-activation-mapping-CAM): Class Activation Mapping (CAM) is used to visualize and understand the decision-making of convolutional neural networks (CNNs) for computer vision tasks.
- [Sentence Transformers for Long-Form Text - Zilliz blog](https://zilliz.com/learn/Sentence-Transformers-for-Long-Form-Text): Deep diving into modern transformer-based embeddings for long-form text.
- [How to Get the Right Vector Embeddings - Zilliz blog](https://zilliz.com/blog/how-to-get-the-right-vector-embeddings): A comprehensive introduction to vector embeddings and how to generate them with popular open-source models.
- [Building a Video Analysis System with Milvus Vector Database - Zilliz blog](https://zilliz.com/blog/milvus-helps-analyze-videos-intelligently): Learn how Milvus powers the AI analysis of video content.
- [Time Series Embedding in Data Analysis | Zilliz Learn - Zilliz blog](https://zilliz.com/learn/time-series-embedding-data-analysis): Learn about time series data including general concepts and preprocessing methods to transform time series data into an embedding suitable for forecasting tasks.
- [What Is Recurrent Neural Network? A Simple Reference](https://zilliz.com/glossary/recurrent-neural-networks): In this post, we'll discuss recurrent neural network. We'll cover the types of neural networks, how they work, use cases, and best practices.
- [Everything You Need to Know About Zero Shot Learning - Zilliz blog](https://zilliz.com/learn/what-is-zero-shot-learning): A comprehensive guide to Zero-Shot Learning, covering its methodologies, its relations with similarity search, and popular Zero-Shot Classification Models.
- [What is a Generative Adversarial Network? An Easy Guide](https://zilliz.com/glossary/generative-adversarial-networks): Just like we classify animal fossils into domains, kingdoms, and phyla, we classify AI networks, too. At the highest level, we classify AI networks as "discriminative" and "generative." A generative neural network is an AI that creates something new. This differs from a discriminative network, which classifies something that already exists into particular buckets. Kind of like we're doing right now, by bucketing generative adversarial networks (GANs) into appropriate classifications.
So, if you were in a situation where you wanted to use textual tags to create a new visual image, like with Midjourney, you'd use a generative network. However, if you had a giant pile of data that you needed to classify and tag, you'd use a discriminative model.
- [An Introduction to Vector Embeddings: What They Are and How to Use Them - Zilliz blog](https://zilliz.com/learn/everything-you-should-know-about-vector-embeddings): In this blog post, we will understand the concept of vector embeddings and explore its applications, best practices, and tools for working with embeddings.