chore: init

Author: ritch

README.md

@@ -1,24 +1,240 @@
-# aloha-template
+## FiftyOne Plugin Examples 🔌🚀
 
-<!-- markdownlint-disable no-inline-html line-length -->
-<div align="center">
-<p align="center">
+FiftyOne provides a powerful
+[plugin framework](https://docs.voxel51.com/plugins/index.html) that allows for
+extending and customizing the functionality of the tool.
 
-<img src="https://user-images.githubusercontent.com/25985824/106288517-2422e000-6216-11eb-871d-26ad2e7b1e59.png" height="55px" alt="Voxel51 logo"> &nbsp;
-<img src="https://user-images.githubusercontent.com/25985824/106288518-24bb7680-6216-11eb-8f10-60052c519586.png" height="50px" alt="FiftyOne logo">
+With plugins, you can add new functionality to the FiftyOne App, create
+integrations with other tools and APIs, render custom panels, and add custom
+buttons to menus.
 
-</p>
-</div>
-<!-- markdownlint-enable no-inline-html line-length -->
+With
+[FiftyOne Teams](https://docs.voxel51.com/teams/teams_plugins.html#delegated-operations),
+you can even write plugins that allow users to execute long-running tasks from
+within the App that run on a connected compute cluster.
 
----
+This repository contains a comprehensive collection of **FiftyOne Plugin Examples**
+designed to inspire and educate you on how to build your own plugins. Each example
+demonstrates different aspects of the plugin system and serves as a learning resource
+for developers looking to extend FiftyOne's functionality.
 
-Aloha Team Template. Files in this repository include:
+For example, here's a taste of what you can build with the plugin framework!
 
-1. .github/CODEOWNERS
-1. .github/pull_request_template.md
-1. .github/workflows/pre-commit.yml
-1. .markdownlint.yaml
-1. .pre-commit-config.yaml
-1. .tool-versions
-1. Makefile
+https://github.com/voxel51/fiftyone-plugins/assets/25985824/128d9fbd-9835-49e8-bbb9-93ea5093871f
+
+## Table of Contents
+
+This repository contains a curated collection of
+[FiftyOne Plugin Examples](https://docs.voxel51.com/plugins/index.html), organized into
+the following categories:
+
+-   [Core Examples](#core-examples): fundamental examples that demonstrate essential plugin concepts and patterns
+-   [Operator Examples](#operator-examples): examples showing how to build custom operators and operations
+-   [Panel Examples](#panel-examples): examples demonstrating how to create custom panels and visualizations
+-   [Integration Examples](#integration-examples): examples showing how to integrate with external tools and APIs
+-   [Advanced Examples](#advanced-examples): complex examples showcasing advanced plugin capabilities
+
+## Core Examples
+
+<table>
+    <tr>
+        <th>Name</th>
+        <th>Description</th>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/skeleton">skeleton</a></b></td>
+        <td>🦴 A minimal plugin template showing the basic structure and components needed to get started</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/hello-world">hello-world</a></b></td>
+        <td>👋 A simple example that contains both Python and JavaScript components to demonstrate cross-language plugin development</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/basic-operator">basic-operator</a></b></td>
+        <td>⚙️ Learn how to create your first custom operator with input/output schemas and execution logic</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/basic-panel">basic-panel</a></b></td>
+        <td>📊 Create your first custom panel to display data and interact with your FiftyOne datasets</td>
+    </tr>
+</table>
+
+## Operator Examples
+
+<table>
+    <tr>
+        <th>Name</th>
+        <th>Description</th>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/operator-examples">operator-examples</a></b></td>
+        <td>⚙️ A comprehensive collection of example operators showing how to use the operator type system to build custom FiftyOne operations</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/data-transformation">data-transformation</a></b></td>
+        <td>🔄 Examples of operators that transform and manipulate dataset fields and metadata</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/external-api">external-api</a></b></td>
+        <td>🌐 Learn how to build operators that integrate with external APIs and services</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/batch-processing">batch-processing</a></b></td>
+        <td>📦 Examples of operators that process multiple samples efficiently</td>
+    </tr>
+</table>
+
+## Panel Examples
+
+<table>
+    <tr>
+        <th>Name</th>
+        <th>Description</th>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/panel-examples">panel-examples</a></b></td>
+        <td>📊 A collection of example panels demonstrating common patterns for building Python panels</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/visualization-panels">visualization-panels</a></b></td>
+        <td>📈 Examples of custom visualization panels using popular charting libraries</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/interactive-panels">interactive-panels</a></b></td>
+        <td>🖱️ Learn how to build interactive panels that respond to user input and selections</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/data-exploration">data-exploration</a></b></td>
+        <td>🔍 Examples of panels designed for exploring and analyzing dataset characteristics</td>
+    </tr>
+</table>
+
+## Integration Examples
+
+<table>
+    <tr>
+        <th>Name</th>
+        <th>Description</th>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/ml-framework-integration">ml-framework-integration</a></b></td>
+        <td>🤖 Examples showing how to integrate with popular ML frameworks like PyTorch, TensorFlow, and scikit-learn</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/cloud-integration">cloud-integration</a></b></td>
+        <td>☁️ Learn how to build plugins that work with cloud storage and compute services</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/database-integration">database-integration</a></b></td>
+        <td>🗄️ Examples of plugins that integrate with external databases and data sources</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/annotation-integration">annotation-integration</a></b></td>
+        <td>✏️ Learn how to integrate with annotation tools and workflows</td>
+    </tr>
+</table>
+
+## Advanced Examples
+
+<table>
+    <tr>
+        <th>Name</th>
+        <th>Description</th>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/delegated-operations">delegated-operations</a></b></td>
+        <td>📡 Examples of plugins that use FiftyOne Teams delegated operations for long-running tasks</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/custom-workflows">custom-workflows</a></b></td>
+        <td>🔄 Complex examples showing how to build multi-step workflows and pipelines</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/real-time-integration">real-time-integration</a></b></td>
+        <td>⚡ Examples of plugins that handle real-time data streams and live updates</td>
+    </tr>
+    <tr>
+        <td><b><a href="plugins/performance-optimization">performance-optimization</a></b></td>
+        <td>🚀 Advanced examples demonstrating techniques for optimizing plugin performance</td>
+    </tr>
+</table>
+
+## Using Examples
+
+### Install FiftyOne
+
+If you haven't already, install
+[FiftyOne](https://github.com/voxel51/fiftyone):
+
+```shell
+pip install fiftyone
+```
+
+### Running examples
+
+To explore these examples, you can clone this repository and run them locally:
+
+```shell
+git clone https://github.com/voxel51/fiftyone-plugin-examples
+cd fiftyone-plugin-examples
+```
+
+Each example directory contains:
+- A `README.md` with detailed instructions
+- Source code demonstrating the concept
+- Any necessary configuration files
+- Instructions for testing and running the example
+
+### Example management
+
+You can use the
+[CLI commands](https://docs.voxel51.com/cli/index.html#fiftyone-plugins) below
+to manage examples you've installed:
+
+```shell
+# List all plugins you've downloaded
+fiftyone plugins list
+
+# List the available operators and panels
+fiftyone operators list
+
+# Disable a particular plugin
+fiftyone plugins disable <name>
+
+# Enable a particular plugin
+fiftyone plugins enable <name>
+```
+
+### Local development
+
+If you plan to develop plugins locally, you can clone the repository and
+symlink it into your FiftyOne plugins directory like so:
+
+```shell
+cd /path/to/fiftyone-plugin-examples
+ln -s "$(pwd)" "$(fiftyone config plugins_dir)/fiftyone-plugin-examples"
+```
+
+### Contributing to this repository 🙌
+
+You're also welcome to contribute to the examples that live natively in this
+repository. Check out the [contributions guide](CONTRIBUTING.md) for
+instructions.
+
+## Join the Community
+
+If you want join a fast-growing community of engineers, researchers, and
+practitioners who love computer vision, join the
+[FiftyOne Discord community](https://community.voxel51.com/?_gl=1*1ph47fb*_gcl_au*NjI4MTMwMzIxLjE3MzY0NTM0MDc.) 🚀🚀🚀
+
+**💡 Pro tip:** the `#plugins` channel is a great place to discuss plugin development!
+
+## About FiftyOne
+
+If you've made it this far, we'd greatly appreciate if you'd take a moment to
+check out [FiftyOne](https://github.com/voxel51/fiftyone) and give us a star!
+
+FiftyOne is an open source library for building high-quality datasets and
+computer vision models. It's the engine that powers this project.
+
+Thanks for visiting! 😊

plugins/skeleton/.gitignore

@@ -0,0 +1,36 @@
+# Node modules
+node_modules/
+
+__pycache__
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Dependency directories
+jspm_packages/
+
+# Optional npm cache directory
+.npm/
+.yarn/install-state.gz
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# Mac system files
+.DS_Store

plugins/skeleton/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

plugins/skeleton/README.md

@@ -0,0 +1,56 @@
+This is a template for writing and building a Javascript panel plugin in FiftyOne. Once a plugin is built (as a bundled UMD file), it can be loaded into FiftyOne.
+
+The three most important / notable files are described below.
+
+## 1. `fiftyone.yml`
+
+This file is a manifest for the plugin. It contains metadata about the plugin, such as its name, description, operators, and secrets.
+
+## 2. `package.json`
+
+As a Javascript plugin, this file is used to manage the dependencies of the plugin. Some notable entries in this file are:
+
+a. `main`: This is the entry point of the plugin. It is the file that will be loaded when the plugin is initialized. Make sure `@fiftyone/plugins::registerComponent()` is called in this file.
+
+b. `fiftyone::script`: This is a custom field that is used to specify the path to the bundled UMD script that will be loaded in the panel.
+
+c. `dependencies`: If you have any FiftyOne dependencies, you'll want to use a portal to reference them. The portal should point to the path of the dependency in the local FiftyOne repository.
+
+d. `devDependencies`: In addition to dependencies you may introduce, add a dev dependency on `@voxel51/fiftyone-js-plugin-build`. Also make sure to also declare the peer dependencies of the [fiftyone-js-plugin-build](https://github.com/voxel51/fiftyone-js-plugin-build) package.
+
+e. `resolutions`: Also used to resolve dependency conflicts, this is usually used in this context to resolve portal references.
+
+## 3. `vite.config.ts`
+
+This file is used to configure the Vite build tool. It is used to bundle the plugin into a UMD script that can be loaded in the panel. The `defineConfig` function from the `fiftyone-js-plugin-build` package is used to define the Vite configuration. The `defineConfig` function takes two arguments: the directory of the plugin and an optional configuration object. The configuration object can be used to override the default Vite configuration. For example, you can use it to specify whether or not to generate sourcemaps. The `defineConfig` function returns a Vite configuration object that can be used to build the plugin. An example of how to use the `defineConfig` function is shown below:
+
+```js
+import { defineConfig } from "@voxel51/fiftyone-js-plugin-build";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const dir = __dirname;
+
+const myAdditionalVitePlugins = [
+    // add any additional Vite plugins here
+];
+
+export default defineConfig(dir, {
+  buildConfigOverride: { sourcemap: true },
+  plugins: myAdditionalVitePlugins,
+});
+```
+
+## Important
+
+Before running `yarn build`, make sure you have a local copy of FiftyOne and `FIFTYONE_DIR` is set to the root of the FiftyOne repository.
+
+See also [Fiftyone JS Plugin Build Utils](https://github.com/voxel51/fiftyone-js-plugin-build).
+
+## Troubleshooting
+
+### `yarn` or `yarn install` fails
+
+1. Make sure you have the right version of `yarn` in your `PATH`. You can check the version by running `yarn --version`. If you have `corepack` installed (available by default in node v16+), you'll be auto prompted to install the right version of `yarn` when you run `yarn` or `yarn install` in the plugin directory.

plugins/skeleton/dist/index.umd.js

@@ -0,0 +1,9 @@
+name: "@voxel51/hello-world"
+description: An example of a simple FiftyOne Javascript plugin
+version: 1.0.0
+fiftyone:
+  version: "*"
+url: https://github.com/voxel51/hello-world-plugin-js
+license: Apache 2.0
+operators:
+  - show_alert