Skip to main content

Getting Started with Filters

Welcome to the Getting Started guide for building and running Filters! This tutorial walks you through the essential steps:

  1. Installing Docker
  2. Setting up Git
  3. Configuring Google Cloud (gcloud)
  4. Creating a “Hello World” Filter from a template

Use this guide as a baseline for your local development environment and initial filter creation.

1. Prerequisites & Environment​

Operating System​

  • macOS, Linux, or Windows 10/11 (Pro or Enterprise) with Docker Desktop support.

Required Tools​

  • Docker: For running Filters as containers.
  • Git: To clone repositories, manage your code.
  • gcloud (optional but recommended): If you plan to pull/push Docker images from Google Cloud.
  • Python 3.10+ (recommended): Although Filters can run in Docker, Python is helpful for some optional local tooling.

2. Installing Docker​

  1. Download & Install Docker

    • macOS/Windows: Install Docker Desktop. Ensure it’s running.
    • Linux: Install Docker Engine via your package manager.

  2. Verify Installation: Open a terminal and run:

    docker --version

    You should see the Docker version if everything is set up correctly.

3. Setting Up Git​

  1. Install Git

    • macOS: Often preinstalled, or install via Homebrew: brew install git
    • Windows: Use Git for Windows.
    • Linux: Install via your package manager, e.g. sudo apt-get install git.

  2. Configure Git: Run:

    git config --global user.name "Your Name"
    git config --global user.email "you@example.com"

  3. Verify:

    git --version

4. (Optional) Setting Up gcloud​

If you’ll be pulling or pushing Docker images to Google Cloud:

  1. Install gcloud: Follow instructions at Google Cloud SDK.
  2. Authenticate: 
    gcloud auth login
  3. Configure Docker Authentication: 
    gcloud auth configure-docker
    This allows Docker to push/pull images from Container Registry or Artifact Registry.

5. Creating a “Hello World” Filter​

Now that you have Docker, Git, and optional gcloud configured, let’s build a simple Filter using Plainsight’s filter template.

Step 1: Clone the Template Repo​

  1. Navigate to a directory of your choice: 
    cd ~/dev
  2. Clone the repository: 
    git clone https://github.com/PlainsightAI/filter-template.git my-hello-filter

Note: Replace my-hello-filter with your desired folder name.

Step 2: Customize the Template​

  1. Enter the repo directory: 
    cd my-hello-filter
  2. Rename references inside pyproject.toml, README.md, and any references to the project name:
    • For instance, rename filter_template to filter_hello.
  3. Run the template initialization (if provided) to replace placeholders: 
    ./templatize

    If you’re on Windows, you may need to run this via Git Bash or WSL.

Step 3: Implement “Hello World” Logic​

Inside the template’s main filter file (e.g., filter_hello/filter.py), look for a process() function. You can do something like:

from filter_runtime import Filter

class HelloWorldFilter(Filter):
    def process(self, frames):
        # Print or log a greeting (or manipulate frames)
        self.log.info("Hello from HelloWorldFilter!")
        return frames  # pass frames downstream unmodified

Tip: self.log.info(...) writes to the Filter’s internal logs.

Step 4: Build & Run the Filter​

Most template repos include a Makefile or docker-compose.yaml. For a basic local run:

# Build docker image (assuming you have a Dockerfile)
make build-image

# Run the container
make run-image

Alternatively, if you see a docker-compose.yaml, you can:

docker compose up --build

Note: The template might have environment variables or steps to place a model file, which you can skip for “Hello World.”

When the filter starts, you should see logs printing your greeting.

6. Next Steps​

  • Explore Our Documentation: Read the Filters Overview to learn about different filter types.
  • Add a Model: Try integrating a lightweight model for image classification.
  • Publish & Deploy: Use gcloud or your own Docker registry to share your Filter.
  • Scale Up: Investigate Plainsight’s Vision Stream, Vision Flow, or Vision Edge for production deployments.

Troubleshooting​

  • Docker Permissions: If you encounter issues running Docker commands, ensure your user is in the docker group on Linux, or Docker Desktop is running on macOS/Windows.
  • gcloud Auth: Make sure you’ve run gcloud auth configure-docker if pushing to Google Cloud.
  • Check Logs: When something goes wrong, tail logs in your console or Docker output to see Filter or environment errors.

Questions?​

If you have any questions or run into issues, check our Support & Troubleshooting Guide, or reach out on our community forums. Happy coding!