Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

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

Aberta
  • Algo errado?
#122 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
25/100
Tipo de issue
Documentação
Clareza
Precisa de esclarecimento
Status de atividade
Ativa
Stack de tecnologia
numpy, opencv, python
Domínio
computer-vision, documentation

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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

Linguagem predominante
Python
Estrelas
223
Forks
30
Merge médio
1h 4min
PRs com merge (30d)
9

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de petercorke/machinevision-toolbox-python

Todas as issues de petercorke/machinevision-toolbox-python

Issues semelhantes

Mais issues de Python

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.