Merge pull request #13 from minimaxir/v0.4

V0.4

README.md

@@ -6,7 +6,7 @@ Generate stylistic wordclouds, including gradients and icon shapes!
 
 stylecloud is a Python package that leverages the popular [word_cloud](https://github.com/amueller/word_cloud) package, adding useful features to create truly unique word clouds!
 
-* Icon shapes (of any size!) for wordclouds (via [Font Awesome](https://fontawesome.com) 5.11.2)
+* Icon shapes (of any size!) for wordclouds (via [Font Awesome](https://fontawesome.com) 5.12.0 Free, or your own [Font Awesome Pro](https://github.com/minimaxir/stylecloud-examples/tree/master/fa-pro))
 * Support for advanced color palettes (via [palettable](https://jiffyclub.github.io/palettable/))
 * Manual color selection for text and backgrounds,
 * Directional gradients w/ the aforementioned palettes.
@@ -121,6 +121,9 @@ These parameters are valid for both the Python function and the CLI (you can use
 * font_path: Path to .ttf file for font to use in stylecloud. [default: uses included Staatliches font]
 * random_state: Controls random state of words and colors. [default: `None`]
 * collocations: Whether to include collocations (bigrams) of two words. Same behavior as base `word_cloud` package. [default: `True`]
+* invert_mask: Whether to invert the icon mask, so the words fill the space *except* the icon mask. [default: `False`]
+* pro_icon_path: Path to Font Awesome Pro .ttf file if using FA Pro. [default: `None`]
+* pro_css_path: Path to Font Awesome Pro .css file if using FA Pro. [default: `None`]
 
 ## Helpful Notes
 
@@ -133,10 +136,9 @@ These parameters are valid for both the Python function and the CLI (you can use
 * It's recommended to use FA icons which are large with heavy weight; thin icons might constrain the text too much.
 * If using the default random-color-sampling method, it's recommended to use a qualitative palette. Inversely, if using a gradient, it's recommended to use a *non*qualitative palette (e.g. a sequential palette).
 
-# To Do
+# Projects Using stylecloud
 
-* Support custom font files (e.g. Font Awesome Pro)
-* Create an app running stylecloud
+* [twcloud](https://github.com/minimaxir/twcloud) — Python package + CLI to generate wordclouds of Twitter tweets.
 
 ## Maintainer/Creator
 

setup.py

@@ -5,7 +5,7 @@
 
 stylecloud is a Python package that leverages the popular [word_cloud](https://github.com/amueller/word_cloud) package, adding useful features to create truly unique word clouds!
 
-* Icon shapes (of any size!) for wordclouds (via [Font Awesome](https://fontawesome.com) 5.11.2)
+* Icon shapes (of any size!) for wordclouds (via [Font Awesome](https://fontawesome.com) 5.12.0 Free, or your own Font Awesome Pro)
 * Support for advanced color palettes (via [palettable](https://jiffyclub.github.io/palettable/))
 * Manual color selection for text and backgrounds,
 * Directional gradients w/ the aforementioned palettes.
@@ -19,7 +19,7 @@
 setup(
     name='stylecloud',
     packages=['stylecloud'],  # this must be the same as the name above
-    version='0.3',
+    version='0.4',
     description="Python package + CLI to generate stylistic wordclouds, " \
     "including gradients and icon shapes!",
     long_description=long_description,

stylecloud/stylecloud.py

@@ -42,7 +42,8 @@ def file_to_text(file_path):
         return texts
 
 
-def gen_fa_mask(icon_name='fas fa-grin', size=512, icon_dir='.temp'):
+def gen_fa_mask(icon_name='fas fa-grin', size=512, icon_dir='.temp',
+                pro_icon_path=None, pro_css_path=None):
     """
     Generates a Font Awesome icon mask from the given FA prefix + name.
     """
@@ -55,8 +56,13 @@ def gen_fa_mask(icon_name='fas fa-grin', size=512, icon_dir='.temp'):
     icon_prefix = icon_name.split(' ')[0]
     icon_name_raw = icon_name.split(' ')[1]
 
-    icon = IconFont(css_file=os.path.join(STATIC_PATH, 'fontawesome.min.css'),
-                    ttf_file=os.path.join(STATIC_PATH, font_files[icon_prefix]))
+    css_path = pro_css_path or os.path.join(
+        STATIC_PATH, 'fontawesome.min.css')
+    ttf_path = pro_icon_path or os.path.join(
+        STATIC_PATH, font_files[icon_prefix])
+
+    icon = IconFont(css_file=css_path,
+                    ttf_file=ttf_path)
 
     icon.export_icon(icon=icon_name_raw[len(icon.common_prefix):],
                      size=size,
@@ -75,20 +81,24 @@ def gen_palette(palette):
     return palette_func
 
 
-def gen_mask_array(icon_dir, dtype):
+def gen_mask_array(icon_dir, invert_mask):
     """Generates a numpy array of an icon mask."""
     icon = Image.open(os.path.join(icon_dir, 'icon.png'))
     mask = Image.new("RGBA", icon.size, (255, 255, 255, 255))
     mask.paste(icon, icon)
-    mask_array = np.array(mask, dtype=dtype)
+    mask_array = np.array(mask, dtype='uint8')
+
+    if invert_mask:
+        mask_array = np.invert(mask_array)
 
     return mask_array
 
 
 def gen_gradient_mask(size, palette, icon_dir='.temp',
-                      gradient_dir='horizontal'):
+                      gradient_dir='horizontal', invert_mask=False):
     """Generates a gradient color mask from a specified palette."""
-    mask_array = gen_mask_array(icon_dir, 'float32')
+    mask_array = gen_mask_array(icon_dir, invert_mask)
+    mask_array = np.float32(mask_array)
 
     palette_func = gen_palette(palette)
     gradient = np.array(makeMappingArray(size, palette_func.mpl_colormap))
@@ -139,7 +149,10 @@ def gen_stylecloud(text=None,
                    font_path=os.path.join(STATIC_PATH,
                                           'Staatliches-Regular.ttf'),
                    random_state=None,
-                   collocations=True):
+                   collocations=True,
+                   invert_mask=False,
+                   pro_icon_path=None,
+                   pro_css_path=None):
     """Generates a stylecloud!
     :param text: Input text. Best used if calling the function directly.
     :param file_path: File path of the input text/CSV. Best used on the CLI.
@@ -158,6 +171,9 @@ def gen_stylecloud(text=None,
     :param font_path: Path to .ttf file for font to use in stylecloud.
     :param random_state: Controls random state of words and colors.
     :param collocations: Whether to include collocations (bigrams) of two words.
+    :param invert_mask: Whether to invert the icon mask.
+    :param pro_icon_path: Path to Font Awesome Pro .ttf file if using FA Pro.
+    :param pro_css_path: Path to Font Awesome Pro .css file if using FA Pro.
     """
 
     assert any([text, file_path]
@@ -166,13 +182,13 @@ def gen_stylecloud(text=None,
     if file_path:
         text = file_to_text(file_path)
 
-    gen_fa_mask(icon_name, size, icon_dir)
+    gen_fa_mask(icon_name, size, icon_dir, pro_icon_path, pro_css_path)
 
     if gradient and colors is None:
         pal_colors, mask_array = gen_gradient_mask(size, palette, icon_dir,
-                                                   gradient)
+                                                   gradient, invert_mask)
     else:  # Color each word randomly from the palette
-        mask_array = gen_mask_array(icon_dir, 'uint8')
+        mask_array = gen_mask_array(icon_dir, invert_mask)
         if colors:
             # if specifying a single color string
             if isinstance(colors, str):