Skip to content

Commit

Permalink
Standardise the normalize spelling in importers. (#700)
Browse files Browse the repository at this point in the history 
* Standardise the normalize spelling in importers.

* Add the normalise as deprecated option for importers.

* Correct spelling mistake.

* Refactor normalise warning into helper

* Documentation fixes for normalise [ci skip]

* Change normalals 'normalise' to 'normalize'

This is not public API so it's fine.
  • Loading branch information
@grigorisg9gr
grigorisg9gr authored and Patrick Snape committed Jun 1, 2016
1 parent 803c7d9 commit 8df15df
Show file tree
Hide file tree
Showing 11 changed files with 166 additions and 118 deletions.
18 changes: 9 additions & 9 deletions menpo/feature/features.py
View file
Expand Up @@ -794,12 +794,12 @@ def normalize(img, scale_func=None, mode='all',
error_on_divide_by_zero : `bool`, optional
If ``True``, will raise a ``ValueError`` on dividing by zero.
If ``False``, will merely raise a warning and only those values
with non-zero denominators will be normalised.
with non-zero denominators will be normalized.
Returns
-------
pixels : :map:`Image` or subclass or ``(X, Y, ..., Z, C)`` `ndarray`
A normalised copy of the image that was passed in.
A normalized copy of the image that was passed in.
Raises
------
Expand Down Expand Up @@ -858,12 +858,12 @@ def normalize_norm(pixels, mode='all', error_on_divide_by_zero=True):
error_on_divide_by_zero : `bool`, optional
If ``True``, will raise a ``ValueError`` on dividing by zero.
If ``False``, will merely raise a warning and only those values
with non-zero denominators will be normalised.
with non-zero denominators will be normalized.
Returns
-------
pixels : :map:`Image` or subclass or ``(X, Y, ..., Z, C)`` `ndarray`
A normalised copy of the image that was passed in.
A normalized copy of the image that was passed in.
Raises
------
Expand Down Expand Up @@ -898,12 +898,12 @@ def normalize_std(pixels, mode='all', error_on_divide_by_zero=True):
error_on_divide_by_zero : `bool`, optional
If ``True``, will raise a ``ValueError`` on dividing by zero.
If ``False``, will merely raise a warning and only those values
with non-zero denominators will be normalised.
with non-zero denominators will be normalized.
Returns
-------
pixels : :map:`Image` or subclass or ``(X, Y, ..., Z, C)`` `ndarray`
A normalised copy of the image that was passed in.
A normalized copy of the image that was passed in.
Raises
------
Expand All @@ -921,7 +921,7 @@ def unit_std(x, axis=None):
@ndfeature
def normalize_var(pixels, mode='all', error_on_divide_by_zero=True):
r"""
Normalize the pixels to be mean centred and normalise according
Normalize the pixels to be mean centred and normalize according
to the variance.
The ``mode`` parameter selects whether the normalisation is computed across
all pixels in the image or per-channel.
Expand All @@ -939,12 +939,12 @@ def normalize_var(pixels, mode='all', error_on_divide_by_zero=True):
error_on_divide_by_zero : `bool`, optional
If ``True``, will raise a ``ValueError`` on dividing by zero.
If ``False``, will merely raise a warning and only those values
with non-zero denominators will be normalised.
with non-zero denominators will be normalized.
Returns
-------
pixels : :map:`Image` or subclass or ``(X, Y, ..., Z, C)`` `ndarray`
A normalised copy of the image that was passed in.
A normalized copy of the image that was passed in.
Raises
------
Expand Down
2 changes: 1 addition & 1 deletion menpo/feature/optional/vlfeat.py
View file
Expand Up @@ -165,7 +165,7 @@ def hellinger_vector_128_dsift(x, dtype=np.float32):
**must** be square and the output vector will *always* be a ``(128,)``
vector. Please see :func:`dsift` for more information.
The output of :func:`vector_128_dsift` is normalised using the hellinger
The output of :func:`vector_128_dsift` is normalized using the hellinger
norm (also called the Bhattacharyya distance) which is a measure
designed to quantify the similarity between two probability distributions.
Since SIFT is a histogram based feature, this has been shown to improve
Expand Down
4 changes: 2 additions & 2 deletions menpo/image/test/image_patches_test.py
View file
Expand Up @@ -31,7 +31,7 @@ def test_float_type():


def test_uint8_type():
image = mio.import_builtin_asset('breakingbad.jpg', normalise=False)
image = mio.import_builtin_asset('breakingbad.jpg', normalize=False)
patch_shape = (16, 16)
patches = image.extract_patches(image.landmarks['PTS'].lms,
patch_shape=patch_shape,
Expand Down Expand Up @@ -60,7 +60,7 @@ def test_int_pointcloud():


def test_uint8_type_single_array():
image = mio.import_builtin_asset('breakingbad.jpg', normalise=False)
image = mio.import_builtin_asset('breakingbad.jpg', normalize=False)
patch_shape = (16, 16)
patches = image.extract_patches(image.landmarks['PTS'].lms,
patch_shape=patch_shape,
Expand Down
82 changes: 61 additions & 21 deletions menpo/io/input/base.py
View file
Expand Up @@ -4,7 +4,8 @@
from pathlib import Path
import random

from menpo.base import menpo_src_dir_path, LazyList, partial_doc
from menpo.base import (menpo_src_dir_path, LazyList, partial_doc,
MenpoDeprecationWarning)
from menpo.compatibility import basestring
from menpo.visualize import print_progress

Expand All @@ -14,6 +15,21 @@
ffmpeg_video_types)


# TODO: Remove once deprecated
def _parse_deprecated_normalise(normalise, normalize):
if normalise is not None and normalize is not None:
raise ValueError('normalise is now deprecated, do not set both '
'normalize and normalise.')
elif normalise is not None:
warnings.warn('normalise is no longer supported and will be removed in '
'a future version of Menpo. Use normalize instead.',
MenpoDeprecationWarning)
normalize = normalise
elif normalize is None:
normalize = True
return normalize


def _data_dir_path(base_path):
r"""A path to the built in ./data folder on this machine.
Expand Down Expand Up @@ -70,6 +86,13 @@ def _import_builtin_asset(data_path_to, object_types, landmark_types,
asset :
An instantiated :map:`Image` or :map:`LandmarkGroup` asset.
"""
if kwargs != {}:
normalize = _parse_deprecated_normalise(kwargs.get('normalise'),
kwargs.get('normalize'))
kwargs['normalize'] = normalize
if 'normalise' in kwargs:
del kwargs['normalise']

asset_path = data_path_to(asset_name)
# Import could be either an image or a set of landmarks, so we try
# importing them both separately.
Expand Down Expand Up @@ -193,7 +216,8 @@ def same_name_video(path, frame_number,
return {p.suffix[1:].upper(): p for p in paths_callable(pattern)}


def import_image(filepath, landmark_resolver=same_name, normalise=True):
def import_image(filepath, landmark_resolver=same_name, normalize=None,
normalise=None):
r"""Single image (and associated landmarks) importer.
If an image file is found at `filepath`, returns an :map:`Image` or
Expand All @@ -212,30 +236,33 @@ def import_image(filepath, landmark_resolver=same_name, normalise=True):
image. The function should take one argument (the path to the image) and
return a dictionary of the form ``{'group_name': 'landmark_filepath'}``
Default finds landmarks with the same name as the image file.
normalise : `bool`, optional
If ``True``, normalise the image pixels between 0 and 1 and convert
normalize : `bool`, optional
If ``True``, normalize the image pixels between 0 and 1 and convert
to floating point. If false, the native datatype of the image will be
maintained (commonly `uint8`). Note that in general Menpo assumes
:map:`Image` instances contain floating point data - if you disable
this flag you will have to manually convert the images you import to
floating point before doing most Menpo operations. This however can be
useful to save on memory usage if you only wish to view or crop images.
normalise: `bool`, optional
Deprecated version of normalize. Please use the normalize arg.
Returns
-------
images : :map:`Image` or list of
An instantiated :map:`Image` or subclass thereof or a list of images.
"""
kwargs = {'normalise': normalise}
normalize = _parse_deprecated_normalise(normalise, normalize)
kwargs = {'normalize': normalize}
return _import(filepath, image_types,
landmark_ext_map=image_landmark_types,
landmark_resolver=landmark_resolver,
landmark_attach_func=_import_object_attach_landmarks,
importer_kwargs=kwargs)


def import_video(filepath, landmark_resolver=same_name_video, normalise=True,
importer_method='ffmpeg'):
def import_video(filepath, landmark_resolver=same_name_video, normalize=None,
normalise=None, importer_method='ffmpeg'):
r"""Single video (and associated landmarks) importer.
If a video file is found at `filepath`, returns an :map:`LazyList` wrapping
Expand Down Expand Up @@ -263,14 +290,16 @@ def import_video(filepath, landmark_resolver=same_name_video, normalise=True,
the frame number) and return a dictionary of the form ``{'group_name':
'landmark_filepath'}`` Default finds landmarks with the same name as the
video file, appended with '_{frame_number}'.
normalise : `bool`, optional
If ``True``, normalise the frame pixels between 0 and 1 and convert
normalize : `bool`, optional
If ``True``, normalize the frame pixels between 0 and 1 and convert
to floating point. If ``False``, the native datatype of the image will
be maintained (commonly `uint8`). Note that in general Menpo assumes
:map:`Image` instances contain floating point data - if you disable this
flag you will have to manually convert the farmes you import to floating
point before doing most Menpo operations. This however can be useful to
save on memory usage if you only wish to view or crop the frames.
normalise : `bool`, optional
Deprecated version of normalize. Please use the normalize arg.
importer_method : {'ffmpeg'}, optional
A string representing the type of importer to use, by default ffmpeg
is used.
Expand All @@ -288,7 +317,9 @@ def import_video(filepath, landmark_resolver=same_name_video, normalise=True,
>>> # Lazily load the 100th frame without reading the entire video
>>> frame100 = video[100]
"""
kwargs = {'normalise': normalise}
normalize = _parse_deprecated_normalise(normalise, normalize)

kwargs = {'normalize': normalize}

video_importer_methods = {'ffmpeg': ffmpeg_video_types}
if importer_method not in video_importer_methods:
Expand Down Expand Up @@ -345,8 +376,8 @@ def import_pickle(filepath):


def import_images(pattern, max_images=None, shuffle=False,
landmark_resolver=same_name, normalise=True,
as_generator=False, verbose=False):
landmark_resolver=same_name, normalize=None,
normalise=None, as_generator=False, verbose=False):
r"""Multiple image (and associated landmarks) importer.
For each image found creates an importer than returns a :map:`Image` or
Expand Down Expand Up @@ -379,14 +410,16 @@ def import_images(pattern, max_images=None, shuffle=False,
image. The function should take one argument (the image itself) and
return a dictionary of the form ``{'group_name': 'landmark_filepath'}``
Default finds landmarks with the same name as the image file.
normalise : `bool`, optional
If ``True``, normalise the image pixels between 0 and 1 and convert
normalize : `bool`, optional
If ``True``, normalize the image pixels between 0 and 1 and convert
to floating point. If false, the native datatype of the image will be
maintained (commonly `uint8`). Note that in general Menpo assumes
:map:`Image` instances contain floating point data - if you disable
this flag you will have to manually convert the images you import to
floating point before doing most Menpo operations. This however can be
useful to save on memory usage if you only wish to view or crop images.
normalise : `bool`, optional
Deprecated version of normalize. Please use the normalize arg.
as_generator : `bool`, optional
If ``True``, the function returns a generator and assets will be yielded
one after another when the generator is iterated over.
Expand All @@ -411,10 +444,12 @@ def import_images(pattern, max_images=None, shuffle=False,
>>> rescale_20p = lambda x: x.rescale(0.2)
>>> images = menpo.io.import_images('./massive_image_db/*') # Returns immediately
>>> images.map(rescale_20p) # Returns immediately
>>> images = images.map(rescale_20p) # Returns immediately
>>> images[0] # Get the first image, resize, lazily loaded
"""
kwargs = {'normalise': normalise}
normalize = _parse_deprecated_normalise(normalise, normalize)

kwargs = {'normalize': normalize}
return _import_glob_lazy_list(
pattern, image_types,
max_assets=max_images, shuffle=shuffle,
Expand All @@ -428,8 +463,9 @@ def import_images(pattern, max_images=None, shuffle=False,


def import_videos(pattern, max_videos=None, shuffle=False,
landmark_resolver=same_name_video, normalise=True,
importer_method='ffmpeg', as_generator=False, verbose=False):
landmark_resolver=same_name_video, normalize=None,
normalise=None, importer_method='ffmpeg',
as_generator=False, verbose=False):
r"""Multiple video (and associated landmarks) importer.
For each video found yields a :map:`LazyList`. By default, landmark files
Expand Down Expand Up @@ -470,14 +506,16 @@ def import_videos(pattern, max_videos=None, shuffle=False,
the frame number) and return a dictionary of the form ``{'group_name':
'landmark_filepath'}`` Default finds landmarks with the same name as the
video file, appended with '_{frame_number}'.
normalise : `bool`, optional
If ``True``, normalise the frame pixels between 0 and 1 and convert
normalize : `bool`, optional
If ``True``, normalize the frame pixels between 0 and 1 and convert
to floating point. If ``False``, the native datatype of the image will
be maintained (commonly `uint8`). Note that in general Menpo assumes
:map:`Image` instances contain floating point data - if you disable this
flag you will have to manually convert the frames you import to floating
point before doing most Menpo operations. This however can be useful to
save on memory usage if you only wish to view or crop the frames.
normalise : `bool`, optional
Deprecated version of normalize. Please use the normalize arg.
importer_method : {'ffmpeg'}, optional
A string representing the type of importer to use, by default ffmpeg
is used.
Expand Down Expand Up @@ -511,7 +549,9 @@ def import_videos(pattern, max_videos=None, shuffle=False,
>>> frames.append(frame.rescale(0.2))
>>> videos.append(frames)
"""
kwargs = {'normalise': normalise}
normalize = _parse_deprecated_normalise(normalise, normalize)

kwargs = {'normalize': normalize}
video_importer_methods = {'ffmpeg': ffmpeg_video_types}
if importer_method not in video_importer_methods:
raise ValueError('Unsupported importer method requested. Valid values '
Expand Down

0 comments on commit 8df15df

Please sign in to comment.