alignfaces 1.0.0__tar.gz

alignfaces-1.0.0/LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright 2021 Carl Michael Gaspar
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

alignfaces-1.0.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: alignfaces
+Version: 1.0.0
+Summary: Automatically align and warp face images
+Author-email: Carl Michael Gaspar <carl.michael.gaspar@icloud.com>, "Oliver G.B. Garrod" <oliver.garrod@fabdata.io>
+License: Apache-2.0
+Keywords: face-alignment,face-morphing,psychophysics,psychology-experiments
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: dlib
+Requires-Dist: scikit-image
+Dynamic: license-file
+
+Automatic Face Alignment (AFA)
+================
+Carl M. Gaspar & Oliver G.B. Garrod
+
+#### You have lots of photos of faces like this:
+![](demos/demo_1_alignment/collage_originals.png)
+
+#### But you want to line up all of the faces like this:
+![](demos/demo_1_alignment/collage_aligned.png)
+
+#### Perhaps you would also like to window the faces to show only inner facial features like this:
+![](demos/demo_1_alignment/collage_aligned_windowed.png)
+
+#### All of the above can be done using AFA like this:
+```python
+import alignfaces as afa
+
+faces_path = "/Users/Me/faces_for_my_study/"
+afa.get_landmarks(faces_path)
+aligned_path = afa.align_procrustes(faces_path)
+afa.get_landmarks(aligned_path)
+the_aperture, aperture_path = afa.place_aperture(aligned_path)
+```
+To better understand how to write a script for your specific purposes, we direct you to [demo 1](demos/demo_1_alignment/README.md). [Demo 1](demos/demo_1_alignment/README.md) also describes how AFA alignment works.
+
+All of these functions depend on reliable detection of facial landmarks, which is provided by the [DLIB](http://dlib.net) library. Alignment is based on generalized Procrustes analysis (GPA), which extensively unit tested.
+
+# Additional functions (warping)
+Automatic landmark detection means that it is also easy to separate **shape** and **texture** in order to produce various kinds of **warped** images.
+
+AFA provides functions for two types of face-warping manipulations common in face perception research.
+
+### Morphing between faces
+To learn how to do this please see [demo 2](demos/demo_2_morphing/README.md).
+
+### Enhanced average of facial identity
+To learn how to do this please see [demo 3](demos/demo_3_averaging/README.md).
+
+# Setup
+
+It is highly recommended that you have **conda** installed, preferably **miniconda** rather than full fat **anaconda**.
+
+If you do have **conda**, then this is the easiest way to install:
+
+```bash
+conda create --name myenv "conda-forge::dlib<19.24.2" "python>=3.9" scikit-image
+
+conda activate myenv
+
+conda install -c conda-forge matplotlib
+```
+
+To install AFA next you have two options:
+
+You either do this:
+
+```bash
+pip install "alignfaces @ git+https://git@github.com/SourCherries/auto-face-align.git"
+```
+
+Or if instead you want a readable and editable copy of AFA on your local machine, then first clone this repository, go to the root folder `auto-face-align`, and then do this:
+
+```bash
+pip install .
+```
+
+Regardless of how you installed AFA, the above process will create a new virtual environment called `myenv`. You can use another name for that. You'll need to activate this environment using `conda activate myenv` whenever you want to use AFA. To deactivate, simply type `conda deactivate myenv`.
+
+If you have a readable/editable copy of AFA on your local machine, you will have copies of all the demos. Most users will want those demo scripts to get started on their projects.
+
+Other users may want a readable/editable copy of AFA to contribute to AFA, or to evaluate AFA by running the analyses under `results` or the unit tests. To run the unit tests, go to the root folder `auto-face-align` then do this:
+
+```bash
+pip install -U pytest
+pytest -v src/alignfaces/tests/
+```
+
+# How well does this work?
+In addition to unit-testing critical computations, I evaluated both landmark estimation (DLIB) and the outcome of the entire alignment procedure using various face databases. The results are described [here](results/README.md).
+
+<!-- ## Ensure that you have the proper C compiler
+On Linux, you will already have an appropriate C compiler.
+
+On Windows, you need to install Microsoft Visual Studio.
+
+On Mac, you need to install Xcode Command Line Tools.
+1. Find an Xcode version compatible with your [macOS version](https://en.wikipedia.org/wiki/Xcode).
+2. Get the right version of [Xcode Command Line Tools](https://developer.apple.com/downloads/index.action).
+``` -->
+
+# Citation
+If you use this package for your research, please cite the following preprint:
+>Gaspar, C. M., & Garrod, O. G. B. (2021, November 8). A Python toolbox for Automatic Face Alignment (AFA). Retrieved from psyarxiv.com/erc8a
+
+DOI:
+>10.31234/osf.io/erc8a
+
+# License
+This module is under an Apache-2.0 license.

alignfaces-1.0.0/README.md

@@ -0,0 +1,99 @@
+Automatic Face Alignment (AFA)
+================
+Carl M. Gaspar & Oliver G.B. Garrod
+
+#### You have lots of photos of faces like this:
+![](demos/demo_1_alignment/collage_originals.png)
+
+#### But you want to line up all of the faces like this:
+![](demos/demo_1_alignment/collage_aligned.png)
+
+#### Perhaps you would also like to window the faces to show only inner facial features like this:
+![](demos/demo_1_alignment/collage_aligned_windowed.png)
+
+#### All of the above can be done using AFA like this:
+```python
+import alignfaces as afa
+
+faces_path = "/Users/Me/faces_for_my_study/"
+afa.get_landmarks(faces_path)
+aligned_path = afa.align_procrustes(faces_path)
+afa.get_landmarks(aligned_path)
+the_aperture, aperture_path = afa.place_aperture(aligned_path)
+```
+To better understand how to write a script for your specific purposes, we direct you to [demo 1](demos/demo_1_alignment/README.md). [Demo 1](demos/demo_1_alignment/README.md) also describes how AFA alignment works.
+
+All of these functions depend on reliable detection of facial landmarks, which is provided by the [DLIB](http://dlib.net) library. Alignment is based on generalized Procrustes analysis (GPA), which extensively unit tested.
+
+# Additional functions (warping)
+Automatic landmark detection means that it is also easy to separate **shape** and **texture** in order to produce various kinds of **warped** images.
+
+AFA provides functions for two types of face-warping manipulations common in face perception research.
+
+### Morphing between faces
+To learn how to do this please see [demo 2](demos/demo_2_morphing/README.md).
+
+### Enhanced average of facial identity
+To learn how to do this please see [demo 3](demos/demo_3_averaging/README.md).
+
+# Setup
+
+It is highly recommended that you have **conda** installed, preferably **miniconda** rather than full fat **anaconda**.
+
+If you do have **conda**, then this is the easiest way to install:
+
+```bash
+conda create --name myenv "conda-forge::dlib<19.24.2" "python>=3.9" scikit-image
+
+conda activate myenv
+
+conda install -c conda-forge matplotlib
+```
+
+To install AFA next you have two options:
+
+You either do this:
+
+```bash
+pip install "alignfaces @ git+https://git@github.com/SourCherries/auto-face-align.git"
+```
+
+Or if instead you want a readable and editable copy of AFA on your local machine, then first clone this repository, go to the root folder `auto-face-align`, and then do this:
+
+```bash
+pip install .
+```
+
+Regardless of how you installed AFA, the above process will create a new virtual environment called `myenv`. You can use another name for that. You'll need to activate this environment using `conda activate myenv` whenever you want to use AFA. To deactivate, simply type `conda deactivate myenv`.
+
+If you have a readable/editable copy of AFA on your local machine, you will have copies of all the demos. Most users will want those demo scripts to get started on their projects.
+
+Other users may want a readable/editable copy of AFA to contribute to AFA, or to evaluate AFA by running the analyses under `results` or the unit tests. To run the unit tests, go to the root folder `auto-face-align` then do this:
+
+```bash
+pip install -U pytest
+pytest -v src/alignfaces/tests/
+```
+
+# How well does this work?
+In addition to unit-testing critical computations, I evaluated both landmark estimation (DLIB) and the outcome of the entire alignment procedure using various face databases. The results are described [here](results/README.md).
+
+<!-- ## Ensure that you have the proper C compiler
+On Linux, you will already have an appropriate C compiler.
+
+On Windows, you need to install Microsoft Visual Studio.
+
+On Mac, you need to install Xcode Command Line Tools.
+1. Find an Xcode version compatible with your [macOS version](https://en.wikipedia.org/wiki/Xcode).
+2. Get the right version of [Xcode Command Line Tools](https://developer.apple.com/downloads/index.action).
+``` -->
+
+# Citation
+If you use this package for your research, please cite the following preprint:
+>Gaspar, C. M., & Garrod, O. G. B. (2021, November 8). A Python toolbox for Automatic Face Alignment (AFA). Retrieved from psyarxiv.com/erc8a
+
+DOI:
+>10.31234/osf.io/erc8a
+
+# License
+This module is under an Apache-2.0 license.

alignfaces-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "alignfaces"
+authors = [
+    {name = "Carl Michael Gaspar", email = "carl.michael.gaspar@icloud.com"},
+    {name = "Oliver G.B. Garrod", email = "oliver.garrod@fabdata.io"}
+]
+description = "Automatically align and warp face images"
+readme = "README.md"
+keywords = ["face-alignment", "face-morphing","psychophysics","psychology-experiments"]
+license = {text = "Apache-2.0"}
+requires-python = ">=3.9"
+dependencies = [
+    "dlib",
+    "scikit-image"
+]
+version = "1.0.0"
+
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+
+[tool.setuptools.package-data]
+"alignfaces.data" = ["*.dat"]
+"alignfaces.tests.R" = ["*.csv"]

alignfaces-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

alignfaces-1.0.0/src/alignfaces/__init__.py

@@ -0,0 +1,15 @@
+"""
+*******************************************************
+*
+*  AlignFaces - INIT FILE
+*
+*  Version:      Version 1.0
+*  License:      Apache 2.0
+*  Written by:   Carl Michael Gaspar
+*  Created on:   March 14, 2019
+*  Last updated: March 14, 2019
+*
+*******************************************************
+"""
+
+from .make_aligned_faces import *

alignfaces-1.0.0/src/alignfaces/aperture_tools.py

@@ -0,0 +1,213 @@
+import numpy as np
+# Might need to import below into make_aligned_faces:
+#   from cv2 import imread, cvtColor, COLOR_BGR2GRAY, imwrite
+from skimage.filters import gaussian
+
+
+# Function to fit an ellipse using a very simple method.
+#   Semi-major axis (vertical) length is fixed as argument.
+#   Increase length of semi-minor until widest distance among landmarks fits.
+#   Immediate code above is redundant with this function.
+def fit_ellipse_semi_minor(semi_major, landmarks, center):
+    X, Y = landmarks[0], landmarks[1]
+    CX, CY = center[0], center[1]
+    Xc = X - CX
+    Yc = Y - CY
+    a_min = np.floor((Xc.max() - Xc.min()) * 3 / 10)
+    a = a_min
+    all_in = (((Xc**2/a**2) + (Yc**2/semi_major**2)) <= 1).all()
+    while (not all_in):
+        a += 1
+        all_in = (((Xc**2/a**2) + (Yc**2/semi_major**2)) <= 1).all()
+    return a
+
+
+def make_ellipse_map(semi_minor, semi_major, center, size, soften=True):
+    CX, CY = center[0], center[1]
+    x = np.array([i-CX for i in range(size[1])])
+    y = np.array([i-CY for i in range(size[0])])
+    xv, yv = np.meshgrid(x, y)
+    R = (xv**2) / semi_minor**2 + (yv**2) / semi_major**2
+    if soften:
+        # Soften edges using Butterworth as a function of radius from (CX, CY)
+        filter_n = 10
+        aperture = 1 / np.sqrt(1 + R**(2*filter_n))
+    else:
+        aperture = R <= 1
+    return aperture
+
+
+# Function to make a binary map of a circle within image of size = size.
+def make_circle_map(cxy, radius, size):
+    size = (size[1], size[0])
+    xx = np.array([[x - cxy[0] for x in range(1, size[0]+1)]
+                   for y in range(size[1])])
+    yy = np.array([[y - cxy[1] for y in range(1, size[1]+1)]
+                   for x in range(size[0])]).T
+    rr = np.sqrt(xx**2 + yy**2)
+    return rr <= radius
+
+
+# Function to make binary map selecting for entire image area below below_y
+def make_map_below_y(below_y, size):
+    size = (size[1], size[0])
+    yy = np.array([[y for y in range(1, size[1]+1)] for x in range(size[0])]).T
+    return yy > below_y
+
+
+# Function to make a binary aperture in shape of Moss's Egg.
+#
+#   1. ABC isosceles with point B facing down
+#       a. define upc, midpoint between A and C
+#       b. upc fraction along vector from mean of inter-eye midpoints
+#           to center of all landmarks
+#           i. fraction default is 1/4 but set as argument
+#       c. radius_upper is fraction of ellipse_width
+#           i. defined in ellipse-fitting functions
+#           ii. fraction default is 47/100 but set as argument
+#       d. A is upc shifted left by radius_upper
+#       e. C is upc shifted right by radius_upper
+#       f. B[x] is upc[x] and B[y] is mean of all nose-tips
+#   2. Rest of procedure follows basic construction of Moss's egg
+def make_moss_egg(landmark_features, center, size,
+                  fraction_width=47/100, soften=True):
+    CX, CY = center[0], center[1]
+
+    # Set radius_upper using same method used when fitting an elliptical
+    # aperture.
+    shapes = np.array(landmark_features['AllSubjectsLandmarksDict'])
+    X = shapes[:, 0::2].reshape(-1,)
+    Y = shapes[:, 1::2].reshape(-1,)
+    # Longest vertical length of ellipse that fits within image.
+    if (size[0] / 2) < CY:
+        ellipse_height = (size[0] - CY) * 2
+    elif (size[0] / 2) > CY:
+        ellipse_height = CY * 2
+    else:
+        ellipse_height = size[0]
+    semi_major = ellipse_height / 2
+    semi_minor = fit_ellipse_semi_minor(semi_major=semi_major,
+                                        landmarks=(X, Y),
+                                        center=(CX, CY))
+    ellipse_width = semi_minor * 2
+    radius_upper = ellipse_width * fraction_width
+
+    # Upper circle, centered on upc (midpoint of AC in ABC).
+    #   Top half defines top of Moss Egg.
+    to_center = 1 / 4
+    eye_midpoints = landmark_features['eye_midpoints']
+    eye_midpoint = np.array(eye_midpoints).mean(axis=0)
+    upc = ((CX, CY) - eye_midpoint) * to_center + (eye_midpoint)
+    horizontal_alignment = upc[0]
+
+    # Now make two large circles whose intersection defines middle part.
+
+    # Large circle on left, centered on cac
+    radius_large = radius_upper * 2
+    cac = (horizontal_alignment - radius_upper, upc[1])
+
+    # Large circle on right, centered on cbc
+    cbc = (horizontal_alignment + radius_upper, upc[1])
+
+    # Now make small circle at bottom, centered on lm.
+    nosey = np.array(landmark_features['nose_tips']).mean(axis=0)[1]
+    lm = (horizontal_alignment, nosey)
+
+    # Isosceles triangle cac -- lm -- cbc (ABC) with apex at lm.
+    # Ensure that angle at lm is greater than 60 degrees.
+    v1 = np.asarray(cac) - np.asarray(lm)
+    v2 = np.asarray(cbc) - np.asarray(lm)
+    acos = np.sum(v1 * v2) / (np.sqrt(np.sum(v1**2)) * np.sqrt(np.sum(v2**2)))
+    DegABC = np.arccos(acos) * 180 / np.pi
+    assert DegABC > 60
+
+    # Line defined by A (center of large circle) to lm.
+    #   m * x + y_intercept
+    #   m * x + c
+    delta = np.array(lm) - cac
+    m = delta[1] / delta[0]
+    t_intercept = -cac[0] / delta[0]
+    y_intercept = t_intercept * delta[1] + cac[1]
+
+    # Intersection of Ca with above line.
+    #
+    # (x - cac[0])**2 + (m * x + y_intercept - cac[1])**2 = radius_large**2
+    # (x -      p)**2 + (m * x +           c -      q)**2 =            r**2
+    A = m**2 + 1
+    B = 2 * (m * y_intercept - m*cac[1] - cac[0])
+    C = (cac[1]**2 - radius_large**2 + cac[0]**2 -
+         2*y_intercept*cac[1] + y_intercept**2)
+
+    assert B**2 - 4*A*C > 0
+
+    # Radius defined by distance from lm to above intersection.
+    # x_m = (-B - np.sqrt(B**2 - 4*A*C)) / (2*A)
+    x_p = (-B + np.sqrt(B**2 - 4*A*C)) / (2*A)
+    Ex = x_p
+    Ey = m * Ex + y_intercept
+    lower_radius = np.sqrt((((Ex, Ey) - np.array(lm))**2).sum())
+
+    Ca = make_circle_map(cxy=cac, radius=radius_large, size=size)
+    Cb = make_circle_map(cxy=cbc, radius=radius_large, size=size)
+    Cu = make_circle_map(cxy=upc, radius=radius_upper, size=size)
+    Cc = make_circle_map(cxy=lm, radius=lower_radius, size=size)
+
+    # LM1 = make_map_below_y(below_y=horizontal_alignment, size=size)
+    LM1 = make_map_below_y(below_y=upc[1], size=size)
+    LM2 = make_map_below_y(below_y=Ey, size=size)
+
+    EggA = Cu
+    EggB = Ca & Cb & LM1 & (LM2 == False)
+    EggC = Cc & LM2
+    # plt.imshow(np.c_[EggA, EggB, EggC])
+
+    MossEgg = EggA | EggB | EggC
+
+    if soften:
+        ME = MossEgg.astype(float)
+        IP = landmark_features['IrisPoints']
+        IPD = [np.sqrt(sum((I[1] - I[0])**2)) for I in IP]
+        sigma = round(np.asarray(IPD).mean() * 0.05)
+        MossEgg = gaussian(ME, sigma=(sigma, sigma),
+                           truncate=3.5 * sigma)
+        # MossEgg = gaussian(ME, sigma=(sigma, sigma),
+        #                    truncate=3.5 * sigma, multichannel=False)
+
+    # package critical variables for visualizing moss's egg construction
+    egg_params = {}
+    egg_params['A'] = cac
+    egg_params['B'] = lm
+    egg_params['C'] = cbc
+    egg_params['upc'] = upc
+    egg_params['radius_large'] = radius_large
+    egg_params['radius_upper'] = radius_upper
+    egg_params['radius_lower'] = lower_radius
+
+    return MossEgg, egg_params
+
+
+# Pack all into a four-channel image of unsigned 8-bit integers.
+def make_four_channel_image(img, aperture):
+    # assert aperture.min() >= 0 and aperture.max() <= 1
+    if not (aperture.min() >= 0 and aperture.max() <= 1):
+        aperture = aperture - aperture.min()
+        aperture = aperture / aperture.max()
+    alpha = (aperture * 255).astype(np.uint8)
+    if img.ndim == 2:
+        assert type(img[0, 0]) is np.uint8
+        size = img.shape
+        BGRA = np.zeros((size[0], size[1], 4), np.uint8)
+        for i in range(3):
+            BGRA[:, :, i] = img
+        BGRA[:, :, 3] = alpha
+    elif img.ndim == 3:
+        assert type(img[0, 0, 0]) is np.uint8
+        size = img.shape
+        BGRA = np.zeros((size[0], size[1], 4), np.uint8)
+        for i in range(3):
+            BGRA[:, :, i] = img[:, :, i]
+        BGRA[:, :, 3] = alpha
+    else:
+        BGRA = []
+        print("Warning: Image is neither grayscale nor RGB.")
+    return BGRA

alignfaces-1.0.0/src/alignfaces/contrast_tools.py

@@ -0,0 +1,106 @@
+import numpy as np
+from skimage import exposure
+
+# Ensures that values are centered on 127.5 and either reach until 0 or 255.
+#   full_image, numpy image array (any range of values)
+#   inner_locs, optional numpy binary map of inner face
+#               if supplied, all values are normalized but only properties
+#               within map are centered on 127.5 and reach until 0 or 255.
+#               no clipping occurs within map, but can occur outside.
+#
+#   output image is numpy array, unsigned 8-bit integers.
+def max_stretch_around_127(full_image, inner_locs=None):
+    if inner_locs is None:
+        inner_locs = np.ones(full_image.shape) == 1
+    else:
+        print("\nWarning: application of max_stretch_around_127 to subregion" +
+              "can result in clipping outside that subregion.")
+
+    inner_values = full_image[inner_locs]
+    om = inner_values.mean()  # original mean value within binary map
+    inner_values = inner_values - om
+    if abs(inner_values.max()) > abs(inner_values.min()):
+        S = 127.5 / abs(inner_values.max())
+    elif abs(inner_values.max()) < abs(inner_values.min()):
+        S = 127.5 / abs(inner_values.min())
+
+    full_image = (full_image - om) * S + 127.5
+    return full_image.astype(np.uint8)
+
+
+# Ensures that values are centered on original mean and either reach until 0 or 255.
+#   full_image, numpy image array either [0-1] or [0-255]
+#               if [0-1] then multiplied by 255 to get original mean
+#   inner_locs, optional numpy binary map of inner face
+#               if supplied, all values are normalized but only properties
+#               within map are centered on 127.5 and reach until 0 or 255.
+#               no clipping occurs within map, but can occur outside.
+#
+#   output image is numpy array, unsigned 8-bit integers.
+def max_stretch_around_original_mean(full_image, inner_locs=None):
+    if (full_image.min() >=0) and (full_image.max()<=1):
+        full_image = full_image * 255
+    if inner_locs is None:
+        inner_locs = np.ones(full_image.shape) == 1
+    else:
+        print("\nWarning: application of max_stretch_around_original_mean" +
+              "to subregion can result in clipping outside that subregion.")
+
+    inner_values = full_image[inner_locs]
+    om = inner_values.mean()  # original mean value within binary map
+    inner_values = inner_values - om
+    if abs(inner_values.max()) > abs(inner_values.min()):
+        # S = 127.5 / abs(inner_values.max())
+        # [om to 255]
+        # so maximum should now be equal to 255-om
+        # so multiply all by S where:
+        #     MX * S = 255 - om
+        #     S = (255 - om) / MX
+        S = (255 - om) / inner_values.max()
+    elif abs(inner_values.max()) < abs(inner_values.min()):
+        # S = 127.5 / abs(inner_values.min())
+        # [0 to om]
+        # so minimum should now be equal to -om
+        # so multiply all by:
+        #     MN * S = -om
+        #     S = -om / MN
+        S = -om / inner_values.min()
+    full_image = (full_image - om) * S + om
+    return full_image.astype(np.uint8)
+
+
+def max_stretch(full_image, inner_locs=None):
+    if inner_locs is None:
+        inner_locs = np.ones(full_image.shape) == 1
+    else:
+        print("\nWarning: application of max_stretch to subregion" +
+              "can result in clipping outside that subregion.")
+
+    inner_values = full_image[inner_locs]
+    omin = inner_values.min()  # original mean value within binary map
+    inner_values = inner_values - omin
+    omax = inner_values.max()
+
+    full_image = (full_image - omin) / omax
+    full_image = full_image * 255
+    return full_image.astype(np.uint8)
+
+
+def contrast_stretch(full_image, inner_locs=None, type="max"):
+    if full_image.ndim == 3:
+        assert (type=="max") or (type==None)
+        if type == "max":
+            out_image = exposure.rescale_intensity(full_image)
+        return out_image
+    if type == "max":
+        out_image = max_stretch(full_image, inner_locs)
+    elif type == "mean_127":
+        out_image = max_stretch_around_127(full_image, inner_locs)
+    elif type == "mean_keep":
+        out_image = max_stretch_around_original_mean(full_image, inner_locs)
+    elif type == None:
+        out_image = full_image
+    else:
+        out_image = full_image
+        print("Warning: Invalid argument (type) to constrast_stretch.")
+    return out_image