Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

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

未关闭
  • 哪里不对？
#122 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
25/100
Issue 类型
文档
描述清晰度
需要澄清
活跃度
活跃
技术栈
numpy, opencv, python
领域
computer-vision, documentation

调研方向

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.

由索引模型根据 Issue 内容生成。

描述

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

主要语言
Python
星标
223
派生
30
平均合并
1 小时 4 分钟
30 天内合并 PR
9

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

petercorke/machinevision-toolbox-python 的其他 Issue

查看 petercorke/machinevision-toolbox-python 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。