diff --git a/docs/faq.md b/docs/faq.md index ed9df48..bdc17c4 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -19,6 +19,11 @@ MegaDetector is the [Microsoft AI for Good Lab](https://www.microsoft.com/en-us/ It is a **detector**, not a classifier. It tells you *something is there*, not which species. That is a deliberate choice: one detector generalizes across ecosystems far better than a species classifier, which is usually region-specific. For species identification, pair MegaDetector with a downstream classifier. +## How do I get started with MegaDetector? + +Start with the [Getting Started](getting-started.md) guide, which takes you from a folder of images to your first detections in four steps: decide whether the model fits, pick how to run it, process a small batch, and read the output. If you would rather not write code, run it through [SPARROW Studio](https://github.com/microsoft/SPARROW), [AddaxAI](https://addaxdatascience.com/addaxai/), or the [Hugging Face demo](https://huggingface.co/spaces/ai-for-good-lab/pytorch-wildlife). For the three-line Python version, see [How do I run MegaDetector?](#how-do-i-run-megadetector) below. + + ## What does MegaDetector detect? MegaDetector detects three categories: diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..de2b99e --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,94 @@ +--- +title: "Getting Started with MegaDetector: First Steps for Camera-Trap AI" +description: "Getting started with MegaDetector: decide whether it fits, pick a no-code or pip path, run your first camera-trap batch, and read the detection output." +slug: getting-started +tags: + - getting started + - MegaDetector + - camera trap AI + - quickstart + - run MegaDetector +--- + +# Getting Started with MegaDetector + +New to MegaDetector? This page is the short path from "I have a folder of camera-trap images" to "I have detections I can act on." It walks four steps: decide whether the model fits your project, choose how you want to run it, process a first small batch, and read the results. Each step links to the deeper reference page when you are ready for detail. + +If you only want the three-line code snippet, the [Overview](index.md#quick-start) has it. If you are weighing whether to adopt the model at all, the rest of this page is written for you. + +## Is MegaDetector right for my project? + +MegaDetector finds animals, people, and vehicles in camera-trap photos and draws a scored box around each one. It is a detector, so it tells you that something is present, not which species it is. Pairing it with a classifier adds species identity later (see Step 4). Because a single detector travels across habitats far better than any region-specific species model, the same weights work whether your cameras sit in savanna, boreal forest, or rainforest. + +It is a strong fit when: + +- A large image backlog where most frames are empty is the thing slowing your research down. +- Your project spans several regions or ecosystems and you want one model for all of them. +- You need a quick, dependable first pass before expert reviewers spend time on the images. +- You are deploying on low-power field hardware such as a [SPARROW](https://github.com/microsoft/SPARROW) unit. + +Some inputs need a different tool in the family rather than MegaDetector itself: underwater or sonar imagery, overhead and aerial views, and audio recordings each have a dedicated sibling project linked from the [Camera-Trap AI](camera-trap-ai.md#when-to-use-megadetector) guide. Very small, well-camouflaged, or under-represented species can also score low, so test on a labeled sample before you trust the model at scale. The [FAQ](faq.md#what-species-does-megadetector-support) covers these caveats in one place. + +## Step 1: Pick how you want to run it + +There is no single "correct" entry point. Choose the one that matches how much code you want to write and what hardware you have. + +- **No code, graphical app.** [SPARROW Studio](https://github.com/microsoft/SPARROW), the AI for Good Lab desktop application, and [AddaxAI](https://addaxdatascience.com/addaxai/) (formerly EcoAssist) both run MegaDetector through a point-and-click interface with batch processing and visualization. The [Hugging Face Space](https://huggingface.co/spaces/ai-for-good-lab/pytorch-wildlife) runs it in a browser tab with nothing to install. +- **Python or the command line.** Install the package and call it from a few lines of Python, or use the `megadetector` command. This is the most flexible path and the rest of this page assumes it. +- **Free cloud GPU.** The [Google Colab notebook](https://colab.research.google.com/drive/1rjqHrTMzEHkMualr4vB55dQWCsCKMNXi?usp=sharing) gives you a hosted GPU when your own machine has none. + +For a fuller side-by-side of the surrounding tools, see [Camera-Trap Software and Tools](camera-trap-software.md). + +## Step 2: Run a first small batch + +Start small. Run the model on a handful of images first and check that the results look sane before you scale up. Install the framework: + +```bash +pip install PytorchWildlife +``` + +Then run the current release, MegaDetectorV6, over a folder. The weights download themselves the first time: + +```python +from PytorchWildlife.models import detection as pw_detection + +model = pw_detection.MegaDetectorV6() +results = model.batch_image_detection("path/to/a_few_images/") +``` + +A laptop CPU handles roughly two to five images per second with the compact variant, which is plenty for a trial run of a few hundred frames. No GPU is required to begin. If you prefer to stay out of Python entirely, the same job runs from the terminal: + +```bash +megadetector detect --input ./a_few_images/ --output results.json --model MDV6-yolov10-e +``` + +The [Installation](installation.md) page covers conda environments and GPU setup, and the [CLI reference](cli.md) lists every flag. + +## Step 3: Read the output + +MegaDetector writes one record per image. Each record holds the file path and a list of detections, and every detection carries three things: + +- `category`: `animal`, `person`, or `vehicle`. +- `confidence`: a score from 0 to 1. +- `bbox`: the box as `[x1, y1, x2, y2]` pixel coordinates. + +You apply a confidence threshold to decide what counts. A value between 0.15 and 0.3 on the animal category suits most datasets: it keeps almost every real animal while letting through a few false hits on swaying vegetation or odd lighting. Anything under your threshold is, in effect, a blank you can set aside, which is what makes the first pass clear so much of the review queue. The [Output Format](output_format.md) reference documents the full schema, and the [Camera-Trap AI](camera-trap-ai.md#filtering-blank-camera-trap-images) guide explains the blank-filtering workflow. + +## Step 4: Scale up and add species + +Once a trial batch looks right, the same code scales to a full deployment. A GPU changes the economics: at around fifty images per second, a million-image set finishes in roughly five and a half hours, against several days on CPU. Pick a heavier variant for accuracy or a compact one for speed using the guidance in the [Model Zoo](model_zoo.md). + +Two common next steps: + +- **Identify species.** Feed each MegaDetector box into a downstream classifier. PyTorch-Wildlife ships several, and [MegaDetector-Classifier](https://github.com/microsoft/MegaDetector-Classifier) lets you fine-tune one for your own region. The [Overview](index.md#species-classification) shows the two-stage pipeline in code. +- **Fine-tune the detector.** If your species or habitats are thin in the base model, the [fine-tuning guide](training_guide.md) walks through preparing data and running `megadetector train`. + +Downstream review and analysis tools read MegaDetector results directly, including Timelapse, Wildlife Insights, and CamtrapR; the [software guide](camera-trap-software.md) shows where each one fits. + +## Get help + +- **GitHub Issues:** [microsoft/MegaDetector/issues](https://github.com/microsoft/MegaDetector/issues) for bugs and feature requests. +- **Discord:** [the PyTorch-Wildlife community server](https://discord.gg/TeEVxzaYtm). +- **Email:** [zhongqimiao@microsoft.com](mailto:zhongqimiao@microsoft.com). + +Still deciding? The [FAQ](faq.md) answers the most common questions about accuracy, GPU needs, licensing, and the difference between V5 and V6. diff --git a/docs/index.md b/docs/index.md index 793080b..22e3592 100644 --- a/docs/index.md +++ b/docs/index.md @@ -23,7 +23,7 @@ MegaDetector is an **animal detector**, not a species classifier. For species re > [!TIP] > MegaDetector is part of the [microsoft/Biodiversity](https://github.com/microsoft/Biodiversity) umbrella, the hub for all AI for Good Lab wildlife tools. The full PyTorch-Wildlife framework and model zoo live at [microsoft/Pytorch-Wildlife](https://github.com/microsoft/Pytorch-Wildlife). -This page is the practical user guide for the current release, **MegaDetectorV6**. If you want a one-screen reference, jump to [Quick start](#quick-start); if you're evaluating whether MegaDetector fits your project, the [FAQ](faq.md) answers the most common questions. +This page is the practical user guide for the current release, **MegaDetectorV6**. New here? The [Getting Started](getting-started.md) guide walks you from a folder of images to your first detections step by step. If you want a one-screen reference, jump to [Quick start](#quick-start); if you're evaluating whether MegaDetector fits your project, the [FAQ](faq.md) answers the most common questions. ## Quick start diff --git a/mkdocs.yml b/mkdocs.yml index 9ed25a7..e5bb21f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,6 +72,7 @@ theme: nav: - MegaDetector: - Overview: index.md + - Getting Started: getting-started.md - Installation: installation.md - Model Zoo: model_zoo.md - CLI: cli.md diff --git a/overrides/main.html b/overrides/main.html index eb40151..41742b8 100644 --- a/overrides/main.html +++ b/overrides/main.html @@ -93,6 +93,14 @@ "text": "MegaDetector is the Microsoft AI for Good Lab's open-source model for finding animals, people, and vehicles in camera-trap images. It draws a bounding box around each detected object and gives it a confidence score between 0 and 1. It is a detector, not a classifier: it tells you something is there, not which species. One detector generalizes across ecosystems far better than a region-specific species classifier. For species identification, pair MegaDetector with a downstream classifier." } }, + { + "@type": "Question", + "name": "How do I get started with MegaDetector?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Start with the Getting Started guide, which takes you from a folder of images to your first detections in four steps: decide whether the model fits, pick how to run it, process a small batch, and read the output. If you would rather not write code, run it through SPARROW Studio, AddaxAI, or the Hugging Face demo. For the three-line Python version, see How do I run MegaDetector." + } + }, { "@type": "Question", "name": "What does MegaDetector detect?", @@ -218,6 +226,44 @@ {%- endif %} + {%- if page and page.file and page.file.src_path == "getting-started.md" and page.canonical_url %} + {#- Getting Started page only: HowTo. Steps mirror the visible getting-started.md headings. -#} + + {%- endif %} + {%- if page and page.file and page.file.src_path != "index.md" and page.canonical_url %} {#- Interior pages only: BreadcrumbList (no breadcrumb on the homepage) -#}