Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

MVTB 2 migration guide: unfinished draft (for consideration) and discrepancies found

Open
  • Is something wrong?
#122 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Active
Tech stack
numpy, opencv, python
Domain
computer-vision, documentation

Research direction

Start with the unfinished migration draft in the issue and inspect the Image.threshold implementation and docstring, checking the reported behavior in a clean OpenCV 5.0 environment. Resolve the open decisions, complete or remove the unfinished sections, and publish the result under docs/source/migration with the documented threshold return behavior.

Written by the indexing model from the issue text.

Description

tech-debt

Status: incomplete draft, for consideration. Not a polished design. This is an unfinished set of notes on v1 to v2 changes, written about 6 months ago and parked here from an untracked file (#45). It is not a published migration guide and nothing here is decided.

Why

There is no migration page in the docs, and 2.x is released, so users coming from v1 have nothing telling them what changed (.A / .image to .array, reprs, threshold, Constant signatures, ...).

Fact-check of the draft against 2.4.0 (main at 43c5980c, 2026-10-03)

Run in a clean OpenCV 5.0 venv.

Claim in the draft Result
.array is a read-only property; array_as(dtype) confirmed
img.stats is a dict-valued property; printstats() exists confirmed
binary threshold returns uint8 0/255; as_bool=True gives a bool image confirmed
Image.Constant(value, size=...): size keyword-only, positional Constant(10, 10, 3) rejected confirmed
img.sum, min, max, mean, std, var, median are properties in v2 false: they are still methods in 2.4.0 (im.mean() works, type(Image.mean) is a function)
(not in the draft) threshold('otsu'), 'triangle' and 'percentile' return a tuple (Image, threshold_value), not an Image; the threshold docstring says :return: thresholded image

Things to decide / fix

  1. Is the scalar-stats-as-properties change intended? If yes, it is not done; if no, remove it from the draft. (Related to .stats already being a property.)
  2. Image.threshold returns a tuple for the algorithm options but its docstring says it returns an Image: fix the docstring, and mention the tuple in the migration notes.
  3. Finish or remove the unfinished parts: the empty "Dtype change" heading, and "Shape functions like Image.Squares(2, 10, 10) would create..." which stops mid-sentence.
  4. Then publish as a docs page (e.g. docs/source/migration).

The draft, verbatim

MIGRATION.md (unfinished, as found)

Migration to MVTB 2

Image object

Access to encapsulated pixel data

The Image object keeps a private reference to the numpy array that holds the pixel data. This array should not be
changed directly since it may invalidate the metadata in the object itself.

The private reference was previously either .A or .image. The former is too cryptic and the latter
confusing since it returns an ndarray not an Image.

For v2 this is now .array. It's a read-only property. You can use the referenced array but do not mutate it.

To get an ndarray of a particular type use .array_as(dtype) where dtype is a string or a np datatype.

Dtype change

Reprs

In v1 the str methods were often quite verbose, nicely formatted multiline displays. Some even
displayed tables using ansitable. Most repr methods just called str which is poor practice,
a repr should be concise and single line and ideally be sufficient to recreate the object.

In v2, __repr__s now conform to that model. This means that the old workflow

>>> mvtb_method(...)

would display a verbose response. Now you just get the cryptic version.

Image.threshold()

Image.threshold(t, opt) where t is the threshold that could be a numeric threshold or a string specifying
an algorithm for choosing the threshold. This is modeled on cv.threshold which returns an image the same
type as the source. A bug meant that for floating point images the result would comprise 0 and inf values.
The algorithms for choosing a threshold, otsu and triangle, are limited to uint8/16 and uint8 pixels respectively.

A binary threshold of a floating image should be a boolean image not a float. However boolean images are
not well received by OpenCV, so the decision was made to return uint8 image with pixels as 0 (false) and
255 (true) for the binary threshold case.

Changes:

  • for binary and binary_inv case the return value will always be uint8

  • the as_bool option will return a bool image

  • Otsu and triangle have been implemented from scratch using numpy and handle int or float images

  • a new 'percentile' option has been added

          >>> img.threshold(5).print()
      >>> img.threshold('otsu')
      >>> img.threshold('percentile', p=90)

Image constants

Image.Constant(10, 10, 3) would create a 10x10 image containing pixel values of 3. It is not particularly
informative when read. It could also be written as Image.Constant(w=10, h=10, value=3) which is not much better.
Worse it could be written as Image.Constant((10,10), 3) or Image.Constant(w=(10,10), value=3).
Too many options, and arguably the constant value should come first.

Shape functions like Image.Squares(2, 10, 10) would create...

All these functions now have the following keyword arguments, they cannot be positional.

  • size: tuple a tuple either (W,H) or (W,H,C)
  • dtype: str | Dtype a datatype specifier as either a string or an np.dtype
  • colororder: str specifying the color order of a multi-channel image
  • like: Image where the image sets the defaults for size, dtype and colororder, the options above will override those

The only positional arguments would the ones specific to the method.

Other

Image.stats

Image.stats is now a property (dictionary-valued), not a method.

  • v1: img.stats()
  • v2: img.stats
  • formatted console output: img.printstats()

Whole-image scalar statistics are now properties as well:

  • v1: img.sum(), img.min(), img.max(), img.mean(), img.std(), img.var(), img.median()
  • v2: img.sum, img.min, img.max, img.mean, img.std, img.var, img.median

Related: #45

Dominant language
Python
Stars
223
Forks
30
Avg merge
1h 4m
Merged PRs (30d)
9

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from petercorke/machinevision-toolbox-python

All issues in petercorke/machinevision-toolbox-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.