PHPackages                             biigle/magic-sam - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. biigle/magic-sam

ActiveLibrary[Image & Media](/categories/media)

biigle/magic-sam
================

BIIGLE module for the Magic SAM image annotation instrument .

v1.6.3(2mo ago)05.4k[4 issues](https://github.com/biigle/magic-sam/issues)GPL-3.0-onlyJavaScriptCI passing

Since May 26Pushed 2w ago3 watchersCompare

[ Source](https://github.com/biigle/magic-sam)[ Packagist](https://packagist.org/packages/biigle/magic-sam)[ Docs](https://biigle.de)[ RSS](/packages/biigle-magic-sam/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)DependenciesVersions (40)Used By (0)

BIIGLE Magic SAM Module
=======================

[](#biigle-magic-sam-module)

[![Test status](https://github.com/biigle/magic-sam/workflows/Tests/badge.svg)](https://github.com/biigle/magic-sam/actions?query=workflow%3ATests)

This is a BIIGLE module that offers the Magic SAM image annotation instrument.

Installation
------------

[](#installation)

1. Run `composer require biigle/magic-sam`.
2. Run `php artisan vendor:publish --tag=public` to refresh the public assets of the modules. Do this for every update of this module.
3. Configure a storage disk for the image embedding files. Set the `MAGIC_SAM_EMBEDDING_STORAGE_DISK` variable in the `.env` file to the name of the respective storage disk. The content of the storage disk should be publicly accessible. Example for local disks: ```
    'magic-sam' => [
        'driver' => 'local',
        'root' => storage_path('app/public/magic-sam'),
        'url' => env('APP_URL').'/storage/magic-sam',
        'visibility' => 'public',
    ],
    ```

    This requires the link `storage -> ../storage/app/public` in the `public` directory.

Configuration
-------------

[](#configuration)

Image embeddings are generated by a Python worker process that requires a dedicated Docker Compose configuration. The Docker container can be based on `ghcr.io/biigle/pyworker` but also must satisfy the Python [requirements](requirements.txt) of this repository. The SAM model type and checkpoint URL are configured via environment variables, as shown below. Here is a full example configuration:

```
  magic-sam-pyworker:
    image: magic-sam-pyworker
    user: ${USER_ID}:${GROUP_ID}
    working_dir: /var/www
    volumes:
      - ./:/var/www
    init: true
    environment:
      # The SAM model type.
      # See: https://github.com/facebookresearch/segment-anything#model-checkpoints
      - SAM_MODEL_TYPE=vit_h
      # URL from which to download the model checkpoint (must match the model type above).
      # Important: The model checkpoint must match with the ONNX file (see config/
      # magic_sam.php)!
      - SAM_MODEL_URL=https://dl.fbaipublicfiles.com/segment_anything/sam_vit_h_4b8939.pth
    command: "python vendor/biigle/magic-sam/src/resources/scripts/GenerateEmbeddingWorker.py"
```

While image embeddings can be generated on the CPU it is much faster on a GPU.

Image embedding files are automatically deleted after 30 days. You can configure this with the `MAGIC_SAM_PRUNE_AGE_DAYS` environment variable.

References
----------

[](#references)

Reference publications that you should cite if you use Magic SAM for one of your studies.

- **BIIGLE 2.0**[Langenkämper, D., Zurowietz, M., Schoening, T., & Nattkemper, T. W. (2017). Biigle 2.0-browsing and annotating large marine image collections.](https://doi.org/10.3389/fmars.2017.00083)Frontiers in Marine Science, 4, 83. doi: `10.3389/fmars.2017.00083`
- **Segment Anything**[Kirillov, A., Mintun, E., Ravi, N., Mao, H., Rolland, C., Gustafson, L., Xiao, T., Whitehead, S., Berg, A.C., Lo, W.Y. and Dollár, P., (2023). Segment anything.](https://doi.org/10.48550/arXiv.2304.02643)arXiv preprint arXiv:2304.02643. doi: `10.48550/arXiv.2304.02643`

Developing
----------

[](#developing)

Take a look at the [development guide](https://github.com/biigle/core/blob/master/DEVELOPING.md) of the core repository to get started with the development setup.

Want to develop a new module? Head over to the [biigle/module](https://github.com/biigle/module) template repository.

Contributions and bug reports
-----------------------------

[](#contributions-and-bug-reports)

Contributions to BIIGLE are always welcome. Check out the [contribution guide](https://github.com/biigle/core/blob/master/CONTRIBUTING.md) to get started.

###  Health Score

48

—

FairBetter than 93% of packages

Maintenance91

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 72.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~46 days

Recently: every ~13 days

Total

24

Last Release

73d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2457311?v=4)[Martin Zurowietz](/maintainers/mzur)[@mzur](https://github.com/mzur)

---

Top Contributors

[![mzur](https://avatars.githubusercontent.com/u/2457311?v=4)](https://github.com/mzur "mzur (160 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (29 commits)")[![lehecht](https://avatars.githubusercontent.com/u/72259845?v=4)](https://github.com/lehecht "lehecht (16 commits)")[![dlangenk](https://avatars.githubusercontent.com/u/4822085?v=4)](https://github.com/dlangenk "dlangenk (15 commits)")

---

Tags

biiglebiigle-module

### Embed Badge

![Health badge](/badges/biigle-magic-sam/health.svg)

```
[![Health](https://phpackages.com/badges/biigle-magic-sam/health.svg)](https://phpackages.com/packages/biigle-magic-sam)
```

###  Alternatives

[goat1000/svggraph

Generates SVG graphs

135911.1k3](/packages/goat1000-svggraph)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)