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

Uploaded CPython 3.13Windows x86-64

auspex_seg-0.1.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (13.5 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

auspex_seg-0.1.0-cp313-cp313-macosx_11_0_arm64.whl (2.1 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

auspex_seg-0.1.0-cp312-cp312-win_amd64.whl (1.9 MB view details)

Uploaded CPython 3.12Windows x86-64

auspex_seg-0.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (13.9 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

auspex_seg-0.1.0-cp312-cp312-macosx_11_0_arm64.whl (2.2 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

auspex_seg-0.1.0-cp311-cp311-win_amd64.whl (1.9 MB view details)

Uploaded CPython 3.11Windows x86-64

auspex_seg-0.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (13.4 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

auspex_seg-0.1.0-cp311-cp311-macosx_11_0_arm64.whl (2.2 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

auspex_seg-0.1.0-cp310-cp310-win_amd64.whl (1.9 MB view details)

Uploaded CPython 3.10Windows x86-64

auspex_seg-0.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.7 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

auspex_seg-0.1.0-cp310-cp310-macosx_11_0_arm64.whl (2.2 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

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

File metadata

  • Download URL: auspex_seg-0.1.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 1.8 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.1.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 9f47342f0c8b406133ae6b4b02361464027c8175990ab2ec5ad74ba340520fe9
MD5 a566efeb4a3659b48a1ce872993a66b9
BLAKE2b-256 00c56f764e3a0b66ce0aef3c7a74af4a813071a8f6a790bc1222c9a4d1558fc8

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.1.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ed1c393f8b4de104a3d5cc9dd0fd931a9498e96fe0751e56ba12fdfdd3697ddb
MD5 bfdec5164d7179caaa0be3a579b3b639
BLAKE2b-256 958d9bd18244e010c392043c95c5a40c4779ad05c38fb04ee0c540a24fb4de1f

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.1.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 12dd9504ec847537a353ed27b7fe68dc4542c3b8000a2ea6f5a7e7666b345585
MD5 b73bfd7701e7c6a2e84e37a7f3b41705
BLAKE2b-256 20786d2de87adc5ded183f7010b6215a9c20fdb9cf806e054f035be1d3b7bfdf

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: auspex_seg-0.1.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 1.9 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.1.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 2fdf87ae6076564747f18ff31ae5ddeaa19407d484ded7b0f7b9be0389b1029b
MD5 b107970674efe40979217dbcce035007
BLAKE2b-256 887782a700d29825353360247f2c7b320483c6c12a9a7671ec3c06e153ebfef6

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3ac05200f0045e038f3334334faa6d8f292d0c267cc136f6002ef4a676d94edf
MD5 94c15c20598e8110063bb02d820d3c90
BLAKE2b-256 7d0fc7f3a35bd63cf3ed70087c9cbe4ff3e36ff0f5e2750d38d264b8c7e68db6

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.1.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 361cf5686e387747a4f39641809cedad9391d74ba8885042e4b3c7a81fc80e97
MD5 7224d2fa3da4d06628dd5c839fb01b39
BLAKE2b-256 7a52cd78838640eca7445a2d2354158dda3eb0b57cf3fe8cffb0b5ad35ea5826

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: auspex_seg-0.1.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 1.9 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.1.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 7e60ceb79d1a550defbc9e0dccf80d3550fbb8add39aca0ef84c244bd9f109ea
MD5 eaae0a787585b1c43ba5fc854f04a1f8
BLAKE2b-256 435bf14cbc1fd1849e396ef92426ed795b3a69a781f1de5aaea04f113632dd4f

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 52439ef1f1fd053f5e931f4da81127af82d9e995fa54a42b857921004f44267c
MD5 70d6e4806cc0d761c5cecf656a6e4763
BLAKE2b-256 21bb71235f038dd05115598accfcd2fe8dfdd4d68f5c88d6864c1b691b353376

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.1.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1f40d7b6b187402f9366dff03c552044b33c15c0279382603b8719805147a908
MD5 a4756b981936bf75a445e4d332290660
BLAKE2b-256 457a3458977cb251e418fde72e3339fac07d0e2bdbfe604719046aeb7890f6a5

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: auspex_seg-0.1.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 1.9 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.1.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 67c2ec0d6e5d764ed6b60475bda0e163674d2bed22a15206e184cd1ea8320e1a
MD5 d2bad2c94a1587237cc3cb457d66f417
BLAKE2b-256 2e2fc9378dc2abc2960ab14592464175b2e229e94f721391c29118f567c35751

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 71bff4df4eb1027a43dc41d9d49479d8db473c597bb87bdd517b5cd6fd127817
MD5 0fea94e69c92e12d7971faf5f3fb6b41
BLAKE2b-256 faffd38b16eb8543731a1b7f9919c1fc951b756c310a479ac7216206b7dc89d2

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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.1.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for auspex_seg-0.1.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2fdd2d3900141d592c53b4a12843d0007caedff46b303e3512b8506281e4c879
MD5 12814cc201d198104542d38a9ec73a5e
BLAKE2b-256 f18a989f365eeee738a36a1720b29037e3e299c5a36edac0832afc3a3a6b8ba0

See more details on using hashes here.

Provenance

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

Publisher: wheels.yml on heliontechltd/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

0.2.0

12 files

This release

0.1.0 This release

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