Auspex Seg

Instance segmentation. A polygon per object, with the class and box that identify it — trained on your own annotations.

Trained from random initialisation. No pretrained weights are downloaded and none are required, so the model you train carries nothing of anyone else's.

Install

pip install auspex-seg        # import name: auspex_seg

Wheels for Linux x86_64, Windows and macOS Apple Silicon, Python 3.10–3.13. A GPU makes training much faster, but it is not required: training and prediction both work on a CPU-only install (see Running on CPU below).

Use

from auspex_seg import Auspex

model = Auspex(labelspace="labelspace.yaml")
model.train(data="data.yaml", epochs=150)
results = model.predict("images/", save=True)   # detections carry box + polygons

model = Auspex(weights="best.pt")               # checkpoints are self-contained
model.val(data="data.yaml")

Or the console command: auspex-seg train --data data.yaml --labelspace labelspace.yaml.

Reads COCO JSON, CVAT-for-images 1.1 XML and Pascal VOC XML, mixed freely in one run. Predictions export back to CVAT or COCO for pre-labelling.

Boxes come free

You annotate polygons; you do not annotate boxes. An annotation with only segmentation is complete — the box is taken from the extent of its rings.

The box still exists inside the model, and that is deliberate rather than incidental: mask prototypes are shared across the whole image, so the only thing that makes one of them an instance is its box. Every predicted polygon therefore arrives with a box and a score alongside it, at no extra labelling cost.

A box-only source (Pascal VOC, or a COCO file without segmentation) is accepted and trains the detection half. auspex-seg warns rather than fails if no source supplies polygons at all.

Very small objects

If your objects are only a few pixels across at training resolution, the default detection grid (finest stride 8) cannot resolve them, and a mask cannot be assembled for an instance that was never located. Two approaches, in a train.yaml (micro_batch is not one of them — it is there because the finer grid needs a smaller batch to fit):

model:
  strides: [4, 8, 16, 32]   # adds a finer detection level
train:
  micro_batch: 2            # ~4x the anchors; halve the batch at 768 px
augment:
  native_crop_p: 0.5        # or: train on zoomed windows of large source images

Both are off by default, and they are trades rather than free wins. The finer level roughly doubled F1 on the smallest classes in one measured set, but long thin objects spanning much of the frame tended to fragment into several detections — and because the classification loss is normalised over every anchor, quadrupling the anchor count also pushes predicted confidence down, which hurts most when a dataset has few objects per image. On a set averaging under ten objects an image it suppressed detection entirely. native_crop_p costs no anchors and is the safer first move.

Running on CPU

Training and prediction both work on a CPU-only machine — no NVIDIA driver, a plain pip install torch. Same code path, same checkpoints; verified end to end on torch 2.13.0+cpu, including resuming a GPU-trained checkpoint on a CPU box.

It is slower, so two things are worth knowing.

img_size is the lever. Measured on a 16-core desktop CPU at micro-batch 4, seconds per optimizer step: 9.1 at 640, 5.0 at 448, 3.3 at 320. num_workers makes almost no difference (9.35 at 4 workers against 9.09 at none), and CPU bf16 autocast is 27x slower, not faster — precision resolves to fp32 on CPU automatically and should stay there. Your hardware will differ; the ratios are the useful part.

For prediction, turn off mask refinement. The refinement head runs once per detection, so it dominates CPU inference:

auspex-seg predict --weights best.pt --source images/ --device cpu --no-refine

4.01 s/image down to 0.87 s/image on the same 16-core desktop CPU, over 6 images and 1381 detections. Boxes, classes and scores come back identical. Masks soften at instance edges, and some very small instances lose their polygon altogether — 825 detections carried polygons with refinement on, 724 with it off, on that same run.

From random initialisation a useful run wants a few hundred epochs, so CPU training suits small datasets, pipeline bring-up, and machines where a GPU is not an option — it is not a substitute for one.

Data configuration

labelspace.yaml — your categories, in order; the order is the class id.

data.yaml — one entry per annotation source:

sources:
  - name: batch1
    path: annotations/batch1.json  # COCO .json | CVAT 1.1 XML | VOC xml dir
    images_root: images/
    split: train
    provides: {rect: true, polygon: true}

provides declares what a source actually labels, explicitly — it is never inferred from what happens to be in the file, because an image with zero annotations is a valid negative rather than an unlabelled one.

Sources are validated when training starts: the run prints the image count, how many of them actually carry polygons, and how many sources declared them, and warns when it finds none. That line is worth a glance before walking away from a long job — a manifest that declares polygons over box-only annotations trains a box detector and reports mask mAP of zero several hours later.

A detection's polygons list can be empty when its mask came out too small to trace, so index it defensively.

Growing a model over time: --transfer <checkpoint> continues from existing weights even when classes were added or reordered — the mask pathway is class-agnostic and transfers whole. --source-balance rebalances very unequal sources; --cache-records keeps memory flat on large datasets.

Known limits, stated up front

  • RLE masks are not decoded. A COCO annotation whose segmentation is a dict is marked ignore: it trains nothing at all, neither mask nor box, and only suppresses the background signal where it sits. RLE is the native output of most auto-annotation tools, so an RLE export trains on nothing — check the parser's warning count before assuming a dataset came through intact.
  • Holes train, but do not come back. A ring nested inside another IS subtracted when building the training target, so a donut trains as a donut and the predicted raw mask carries its hole. Polygon output uses only external contours, so the polygons you get back trace the outside and a donut reads as a disc. Use the mask if you need the hole.

Trial and licensing

Training is free for 30 days, in full — no key, no sign-up. The clock starts on your first training run.

Prediction, validation, calibration and export are never gated. They keep working afterwards, on any model you have already trained, forever.

After 30 days, training needs a credential:

export AUSPEX_SEG_LICENSE=AUSPEXSEG-...   # a licence key, or
export AUSPEX_SEG_LICENSE=HLN1....        # an account token
                                          # or write it to ~/.auspex-seg/license.key

Verified offline against a public key compiled into the wheel — nothing phones home, so training works on air-gapped machines. The trade is that a credential cannot be withdrawn before it expires, so they are dated.

Get one: https://heliontechltd.com/license

License

Proprietary, under an End-User License Agreement: licensed users may install and run it and train models on their own data (the resulting weights are theirs); copying, redistribution, modification and reverse engineering are prohibited. Full terms: https://heliontechltd.com/license

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for sohanurislamshuvo from gravatar.com sohanurislamshuvo

Credits

Author: Md. Sohanur Islam Shuvo

License

Other/Proprietary License (AUSPEX END-USER LICENSE AGREEMENT (EULA))

Requires

Python <3.14, >=3.10

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

auspex_seg-0.2.0-cp313-cp313-win_amd64.whl (2.0 MB view details)

Uploaded CPython 3.13Windows x86-64

auspex_seg-0.2.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (15.2 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

auspex_seg-0.2.0-cp313-cp313-macosx_11_0_arm64.whl (2.4 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

auspex_seg-0.2.0-cp312-cp312-win_amd64.whl (2.0 MB view details)

Uploaded CPython 3.12Windows x86-64

auspex_seg-0.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (15.7 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

auspex_seg-0.2.0-cp312-cp312-macosx_11_0_arm64.whl (2.4 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

auspex_seg-0.2.0-cp311-cp311-win_amd64.whl (2.1 MB view details)

Uploaded CPython 3.11Windows x86-64

auspex_seg-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (15.0 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

auspex_seg-0.2.0-cp311-cp311-macosx_11_0_arm64.whl (2.4 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

auspex_seg-0.2.0-cp310-cp310-win_amd64.whl (2.1 MB view details)

Uploaded CPython 3.10Windows x86-64

auspex_seg-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (14.2 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

auspex_seg-0.2.0-cp310-cp310-macosx_11_0_arm64.whl (2.4 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file auspex_seg-0.2.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: auspex_seg-0.2.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 2.0 MB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for auspex_seg-0.2.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 ef75ac770ab517b95113f116b57d90e75ae83dadef4f1f8b758322b48f58e4f0
MD5 b84eef397200782f08f8b520adf09611
BLAKE2b-256 51ee897e02de699d56da4f0c1d5d87d4a69ea1124b62bfd5347dbdf5520fe417

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp313-cp313-win_amd64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 415d453b957f42e654a7ee5bd690bbc1b2160078e0ed8daf08160c4b80ff483b
MD5 a4da3b3fa146ce4f3b88777c705109f4
BLAKE2b-256 f7a304a4882c841191472d64037cec4c70127786d7ba436b2a8e63b8271b4152

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8ab38a035b3a891a787fe1e47e8d8c21eb4c2b802c4cd81850ed0a3350a68fed
MD5 87bdd6d054bb305a4db9ce156952a436
BLAKE2b-256 547f78f74ef9030f17eeb41c4691ddd94574dbf584d66cdc6dcd27b4897e1c54

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: auspex_seg-0.2.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 2.0 MB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for auspex_seg-0.2.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 f35d97339954af738dbb84c8d4f803ed05663599011e2549e681f4764ca98839
MD5 9e4e4f86c1361122bb13fe3fce4d43e3
BLAKE2b-256 bd4028a5fee89fe64b5c88c2e1935de4600d5b4a162bfaf790b0f6df339ebafa

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp312-cp312-win_amd64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c0d9c80db6d62921436e982260a7e996dcc2b2fb31fe9b943cd3e0d95b48d8d1
MD5 b8964f2fd82fd12f31f8e8804ddedd71
BLAKE2b-256 d131274a37a17af735dff7c66ad5bc88cc30971bdd6478cd6b219bb20e821148

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 522ff29e09b2888bf5a94437b57506e9a63e65a1b05840143d4a2f72da961103
MD5 6763a805fdc36e673ecbfbe9bcbe264c
BLAKE2b-256 ce61782be0f45f702a01918a2f28eb136eed5af2e8622c8f00667769df9f20a7

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: auspex_seg-0.2.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 2.1 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for auspex_seg-0.2.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 01f3e70581345f6af18af19c0e4afc6e51f919adc11b9f241ac656eecce586f1
MD5 0f62f732c8bb4a5570ad7eb3a22580b3
BLAKE2b-256 70693437b144b0c9b4166c5c3cedb4e4042bbbe2722b333b4c773722908b68dd

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp311-cp311-win_amd64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 eed04448ef7f88345e875955ca0f5737907ffdcaafa9ae1cd2808bbb139f025f
MD5 206006c6220db4a2ce8396fb8242a124
BLAKE2b-256 45591ac0cf09858e8a0c120d1a07dc8ee1d8ae5616931a612c368e14fdec954f

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1fcf3a2b1a77090227cf5e54648045f749dbc66fe6276e66ca010eb684ab00a1
MD5 22c091f379bacca0a4d91fd297ae2881
BLAKE2b-256 74ecdc3427a437b9765e77b9ef0a9ebe66d840273740238640ad2122993a2d46

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: auspex_seg-0.2.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 2.1 MB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for auspex_seg-0.2.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 6dc32e93b8b1f67bf0a9c7cec36543a306af98a78b1c1c449359432bb3ce5bc9
MD5 181605105ae81a4b1a0dde0d7d1d6b31
BLAKE2b-256 7d92ddcfe946e4a69c21dd736ebe129a0bb688610c62f1902a8e66f22ec2f0d9

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp310-cp310-win_amd64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6b2cc49ff3dd43610e70b92d9abfb7d0af5043b135cad5564904579d281c7931
MD5 9316aa73a78dd9a25442bfa1ceba54aa
BLAKE2b-256 ffc88e61ddf836fe52ff06605e48f4707c76fb43f8351e6f57d7ee5e6de234b8

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auspex_seg-0.2.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 28a7e84c9cc3be6c12e8b61d97951bee393a269087e107ed7f81ee28344d74ed
MD5 a3affeb80e1e13f89c05fe8106ba5066
BLAKE2b-256 360df70336c11bc62682d0e02e2ae968cd4dde889c6f5b5b8a932d36888a9e1a

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.0-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: wheels.yml on Glyphden/auspex-seg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.1

12 files

This release

0.2.0 This release

12 files

0.1.0

12 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page