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:
Latest release

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.1-cp313-cp313-win_amd64.whl (2.1 MB view details)

Uploaded CPython 3.13Windows x86-64

auspex_seg-0.2.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (14.6 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

auspex_seg-0.2.1-cp313-cp313-macosx_11_0_arm64.whl (2.5 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

auspex_seg-0.2.1-cp312-cp312-win_amd64.whl (2.1 MB view details)

Uploaded CPython 3.12Windows x86-64

auspex_seg-0.2.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (15.0 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

auspex_seg-0.2.1-cp312-cp312-macosx_11_0_arm64.whl (2.5 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

auspex_seg-0.2.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (14.6 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

auspex_seg-0.2.1-cp311-cp311-macosx_11_0_arm64.whl (2.5 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

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

Uploaded CPython 3.10Windows x86-64

auspex_seg-0.2.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (13.3 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

auspex_seg-0.2.1-cp310-cp310-macosx_11_0_arm64.whl (2.5 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

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

File metadata

  • Download URL: auspex_seg-0.2.1-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 2.1 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.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 a91b451f0666a848837997fe8544180de2ecc69024108aefe09379aeee284c6d
MD5 0762e244898fac1c4e7147bbf6d9f18c
BLAKE2b-256 bb29749e543e531ab7bdf9a94b36355c87cb58d520e37109f9206a528186f3f3

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6fc8de248d134b755b3dc895b126f24297ee90f6dfc94d0ab93407afe6524f04
MD5 e5540dbe9c7038f3b3c4b3362fe7f29d
BLAKE2b-256 63443fe41ab631849b1dedc1aa422566620874542c4f496114754a95ddd07a8c

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1f1c883cf2d24150559575cc449463db7ec324d5715a27a5be7b10fbf8451727
MD5 99bac8c5026746b1f73eebfaf0125e83
BLAKE2b-256 96b503c0002cdb9ad8035f8d93f4f1edbb9da6736e20e4c8b07521efddadc9a6

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: auspex_seg-0.2.1-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 2.1 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.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 0011a4e20a0c9c2bc9dd033bd03ea8ad348db758b95fc744b1048b4bc54d7f47
MD5 9818e25a33efd782e7b42ce6a6cd9cb7
BLAKE2b-256 ff208fd1f52d607521930a8e1f84797a07454a6a0f75320c4ab28cf42d8d648f

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 980940e363ff339407227dac6e790640aee104366531a0213f3b58f9b3536861
MD5 dbc70c75eb8f7656ad9dbfbefc371563
BLAKE2b-256 1b04a5feb45626ca8d3cfea66e91f7e4970d80a5e7425531f9cc447213ce1dfd

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a69343d70a0905fe0a6a72b3ce7b82be085a3cf37ed2b6f393c5dd054b8069a7
MD5 85f7bb659a8cdfe58d9f21b16bf6dbd2
BLAKE2b-256 b6ea395926677c618650e23214d180345afbdf3675db5db2492cec57a47f4175

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: auspex_seg-0.2.1-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.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 c14d0c73faabbd6fe8742607fc7bc6afd5ca296f603b60a88cb7fa22ec91767b
MD5 88abeefb57080963055cda6574b346da
BLAKE2b-256 7ff52d3d710b10938e329dc387dd7f76045be751ee0803957c699fd71ebd75dc

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 1d8930a7daf272a59acfa51b3797388d57b989125ec2f51b2e99df490d191251
MD5 26eea823bf06ecff53f8d09a9532c0b3
BLAKE2b-256 26d2611c47b1b149fab3d0c51e7d8aaf9ecf6a7d9eeba35e573220e856978f15

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3a2ae4ff8b0ae5dfb74dd5d74e7974b6ae7b09e1ef20ecbb29da2ba44929ff67
MD5 c71ff28e4ea186dd677ef8bcdabce9b6
BLAKE2b-256 deffc968bf72758c83a26aa32ed48923562c005c1a70106a69bcb5e828ed7a3b

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: auspex_seg-0.2.1-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.1-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 1036dbaad16a6e319282278d1e80deb3e24d203e7dd3f29cf972d3b5d7edb6ce
MD5 e4da68635f9db06188dc6a55237485a1
BLAKE2b-256 17e25dc2e0804c6c5d56e061b288db111be5145cb445055cb6b5020216c3b11d

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f18b192c933d7df3d7d13158d43819b1aa98ab05ccf6e57234d54c820350c377
MD5 1b4514e2993783c9f5c500e61b6c9c5a
BLAKE2b-256 bf283a55f09849fe8685b0097fbd97c400566dceb24feb1b2bfa4838fa3f1000

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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.1-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.2.1-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f67439f0d2239950ddbc1fd0afd807807c557c18f14e31a5bb62f20fa0001905
MD5 2d7045f93c45bc96544411363013dce0
BLAKE2b-256 73fc531593ffad47b8fe1634e4e7493d98b0dcbb3b92848abd1291c2c434b39f

See more details on using hashes here.

Provenance

The following attestation bundles were made for auspex_seg-0.2.1-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

This release

0.2.1 This release

12 files

0.2.0

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