Filled in README

Author: dhondta

README.md

@@ -13,15 +13,45 @@
 This library implements multiple plot types for illustrating executable samples. It currently supports the PE, ELF and Mach-O formats, relying on [`lief`](https://github.com/lief-project/LIEF) for abstracting them.
 
 ```sh
-pip install exeplot
+$ pip install exeplot
 ```
 
-## :sunglasses: Usage
+## :sunglasses: Usage Examples
 
-TODO
+Draw a byte plot of `calc_packed.exe`:
+
+```sh
+$ exeplot byte calc_packed.exe
+```
+
+![Byte plot of `calc_packed.exe`](https://github.com/packing-box/python-exeplot/blob/main/docs/pages/img/calc_packed_byte.png?raw=true)
+
+Draw a pie plot of `calc_packed.exe`:
+
+```sh
+$ exeplot pie calc_packed.exe
+```
+
+![Pie plot of `calc_packed.exe`](https://github.com/packing-box/python-exeplot/blob/main/docs/pages/img/calc_packed_pie.png?raw=true)
+
+Draw a nested pie plot of `calc_packed.exe`:
+
+```sh
+$ exeplot nested_pie calc_packed.exe
+```
+
+![Nested pie plot of `calc_packed.exe`](https://github.com/packing-box/python-exeplot/blob/main/docs/pages/img/calc_packed_nested_pie.png?raw=true)
+
+Draw a stacked and scaled entropy plot of `calc_orig.exe` and `calc_packed.exe`:
+
+```sh
+$ exeplot entropy calc_orig.exe calc_packed.exe
+```
+
+![Entropy plot of `calc_orig.exe` and `calc_packed.exe`](https://github.com/packing-box/python-exeplot/blob/main/docs/pages/img/calc_orig_entropy.png?raw=true)
 
 
-## :clap:  Supporters
+## :clap: Supporters
 
 [![Stargazers repo roster for @packing-box/python-exeplot](https://reporoster.com/stars/dark/packing-box/python-exeplot)](https://github.com/packing-box/python-exeplot/stargazers)
 

docs/pages/img/calc_orig_entropy.png

@@ -1 +1 @@
-0.3.1
+0.3.3

docs/pages/img/calc_packed_byte.png

@@ -28,34 +28,38 @@ def human_readable_size(size, precision=0):
     return "%.*f%s" % (precision, size, units[i])
 
 
-def ngrams_counts(byte_obj, n=1):
+def ngrams_counts(byte_obj, n=1, step=1):
     """ Output the Counter instance for an input byte sequence or byte object based on n-grams.
          If the input is a byte object, cache the result.
     
+    :param byte_obj:      byte sequence ('bytes') or byte object with "bytes" and "size" attributes (i.e. pathlib2.Path)
     :param n: n determining the size of n-grams, defaults to 1
+    :param step:          step for sliding the n-grams
     """
     from collections import Counter
     if isinstance(byte_obj, (str, bytes)):
-        return Counter(byte_obj[i:i+n] for i in range(0, len(byte_obj) - n + 1))
+        return Counter(byte_obj[i:i+n] for i in range(0, len(byte_obj)-n+1, step))
     elif hasattr(byte_obj, "bytes") and hasattr(byte_obj, "size"):
         if not hasattr(byte_obj, "_ngram_counts_cache"):
             byte_obj._ngram_counts_cache = {}
         if n not in byte_obj._ngram_counts_cache.keys():
-            byte_obj._ngram_counts_cache[n] = Counter(byte_obj.bytes[i:i+n] for i in range(0, byte_obj.size - n + 1))
+            byte_obj._ngram_counts_cache[n] = Counter(byte_obj.bytes[i:i+n] for i in range(0, byte_obj.size-n+1, step))
         return byte_obj._ngram_counts_cache[n]
     raise TypeError("Bad input type ; should be a byte sequence or object")
 
 
-def ngrams_distribution(byte_obj, n=1, n_most_common=None, n_exclude_top=0, exclude=None):
+def ngrams_distribution(byte_obj, n=1, step=1, n_most_common=None, n_exclude_top=0, exclude=None):
     """ Compute the n-grams distribution of an input byte sequence or byte object given exclusions.
     
+    :param byte_obj:      byte sequence ('bytes') or byte object with "bytes" and "size" attributes (i.e. pathlib2.Path)
     :param n:             n determining the size of n-grams, defaults to 1
+    :param step:          step for sliding the n-grams
     :param n_most_common: number of n-grams to be kept in the result, keep all by default
     :param n_exclude_top: number of n-grams to be excluded from the top of the histogram, no exclusion by default
     :param exclude:       list of specific n-grams to be excluded, no exclusion by default
     :return:              list of n_most_common (n-gram, count) pairs
     """
-    c = ngrams_counts(byte_obj, n)
+    c = ngrams_counts(byte_obj, n, step)
     r = c.most_common(len(c) if n_most_common is None else n_most_common + n_exclude_top + len(exclude or []))
     if exclude is not None:
         r = [(ngram, count) for ngram, count in r if ngram not in exclude]