fourier scramble

scramblery/README.rst

@@ -1,103 +1,127 @@
 # Scramblery |Downloads| |PyPI version| |Jekyll site CI| |Build status|
+|DOI|
+
+.. figure:: https://user-images.githubusercontent.com/54986652/227797464-3fc1fc88-a31b-4244-b99f-df0f77a6e282.png
+   :alt: sacasc
+
+   sacasc
 
 A simple tool to scramble your images or only faces from images or
 videos. You can find the online demo in javascript
 `here <https://altunenes.github.io/scramblery/scramblerydemo.html>`__.
 For more information, please visit the
 `documentation <https://altunenes.github.io/scramblery/>`__.
 
+Note: The Javascript demo doesn’t have a face detection algorithm and
+it’s designed to be applied to a single image. If you want to do this
+for multiple imagees you should use Python.
+
 Purpose of Package
-==================
+~~~~~~~~~~~~~~~~~~
 
-The purpose of this package is the creating scrambled images from images
-or videos. User can either scramble the whole image or only facial area.
-This is very useful tool in psychology experiments especially if you are
-working with faces. With a for loop you can scramble all the images in a
-folder and create a new folder with scrambled images. It was very long
-process to scramble images manually in the past and I feel like this
-package can be useful for many people. Hope this package will be useful
-for your research.
+The Scramblery package offers tools for creating scrambled images from
+existing images or videos. Users have the flexibility to scramble entire
+images or target only specific areas, such as faces. This functionality
+is particularly beneficial in psychological experiments involving facial
+recognition tasks. With Scramblery, users can automate the scrambling of
+multiple images, eliminating the tedious manual process traditionally
+associated with this task. We hope this package significantly
+contributes to your research endeavors.
 
 Motivation
-==========
-
--  Image scrambling is important in psychology experiments because it
-   allows researchers to control the content and structure of visual
-   stimuli, while removing or altering specific features or patterns
-   that might influence participants’ perception or response.
-
--  By scrambling an image, researchers can create a version of the image
-   that preserves the overall luminance, contrast, and spatial layout,
-   but that removes or distorts specific features or patterns that might
-   be relevant for the experiment. For example, researchers might
-   scramble an image of a face to remove the facial features, while
-   preserving the overall brightness and contrast, or they might
-   scramble an image of a scene to remove the objects, while preserving
-   the spatial layout and color.
-
--  It allows researchers to control for potential confounds and biases
-   that might arise from the content of the stimuli. By removing or
-   distorting specific features or patterns, researchers can create
-   stimuli that are less predictable and less likely to elicit specific
-   responses from participants. This can help researchers to isolate the
-   effects of the manipulated variables, and to reduce the influence of
-   confounding factors that might interfere with the interpretation of
-   the results.
-
-**Features**
-============
-
--  Scramble whole image with desired degree of scrambling (pixel values
-   or pixel coordinates)
--  Scramble only facial area with desired degree of scrambling (pixel
-   values or pixel coordinates)
--  Scramble only facial area in a video (useful for dynmaic stimuli)
-   with desired degree of scrambling
+~~~~~~~~~~
+
+-  Image scrambling plays a crucial role in psychology experiments,
+   enabling researchers to manipulate visual stimuli while maintaining
+   control over certain visual aspects. This manipulation helps
+   eliminate or alter specific features or patterns that may influence
+   participants’ perceptions or responses.
+
+-  Scramblery allows for the creation of stimuli that retain general
+   attributes such as luminance, contrast, and spatial layout, but lack
+   identifiable features or objects. This is useful in experiments where
+   researchers wish to control for these specific attributes.
+
+-  The package helps in mitigating biases and confounding variables in
+   stimuli, thereby providing more reliable and valid experimental
+   conditions. The ability to automate this process ensures consistency
+   across stimuli and saves valuable time for researchers.
+
+Features
+~~~~~~~~
+
+-  Scramble an entire image with a specified degree of scrambling
+   (either by altering pixel values or pixel coordinates).
+-  Target scrambling to only the facial area within an image, with
+   customizable levels of scrambling.
+-  Extend the scrambling feature to videos, particularly useful for
+   dynamic stimuli in motion-based experiments.
+-  Leverage Fourier-based scrambling to disrupt the phase information
+   while maintaining the power spectrum, particularly useful for
+   psychophysical studies.
 
 Installation
-============
+~~~~~~~~~~~~
+
+Scramblery is available on PyPI and can be installed using pip. Use the
+following command in your terminal:
+
+.. _installation-1:
+
+Installation
+^^^^^^^^^^^^
 
 -  The package can be found in pypi. To install the package, run the
    following command in the terminal:
 
--  ``pip install scramblery`` #### Author
+-  ``pip install scramblery``
 
-   -  Main Maintainer: [Enes ALTUN]
+-  ``from scramblery import scramblery`` Then use the functions as
+   follows to scramble images. I added some examples below.
 
-Usage
-=====
+   .. figure:: ./docs/assets/usage.PNG
+      :alt: 8x8
+
+      8x8
 
-After installing the package, you can import the package as follows: -
-``from scramblery import scramblery`` Then use the functions as follows
-to scramble images. I added some examples below (see on the Github page)
+   |12x12| |8x8|
+
+Usage
+~~~~~
 
-Code example:
+After installation, you can import and use Scramblery as follows:
 
 .. code:: python
 
    from scramblery import scramblery
-   scramblery.scrambleimage("Lena.png", x_block=10, y_block=10, scramble_type='classic',seed=None,write=True)
-   #note: seed is optional, none means random seed
 
-If you want to scramble images in a folder, check the API section here
-for an example:
-`API <https://altunenes.github.io/scramblery/userguide/>`__.
+   # To scramble an entire image
+   scramblery.scrambleimage("Lena.png", x_block=10, y_block=10, scramble_type='classic', seed=None, write=True)
 
-Javascript Demo
-===============
+   # To scramble only the facial area within an image
+   scramblery.scrambleface("Lena.png", splits=10, type='pixel', seamless=False, bg=True, seed=None, write=True)
 
-Update: Also, with the same paradigm, I have created an animated version
-of scramblery. It’s shuffling pixel values and coordinates in a given
-ratio then it’s arranging them back in the original order. You can find
-the online demo in javascript
-`here <https://altunenes.github.io/scramblery/magic.html>`__.
+   # To apply Fourier-based scrambling on an image
+   scramblery.scrambleimage("Lena.png", scramble_type='fourier', scramble_ratio=0.5, seed=None, write=True)
+   # To apply Fourier-based scrambling o only the facial area within an image
+   scramblery.scrambleface("lena.png",splits=10,type='fourier', scramble_ratio=0.5,write=True)
 
-example (gif animation):
+   # To scramble faces within a video first we need to create a dict.
+   scramble_settings = {
+       'splits': 25,
+       'type': 'pixel',
+       'bg': True,
+       'seed': None,
+       'write': False  # Should always be False for video processing
+   }
+   scramblery.scramblevideo("input_video.mp4", "output_video.mp4", scramble_settings)
 
-Contributon
-===========
+Contribution
+~~~~~~~~~~~~
 
-Any kind of contribution is welcome.
+We welcome contributions of any kind to Scramblery. If you have ideas
+for improvement or have found a bug, please don’t hesitate to
+contribute.
 
 .. |Downloads| image:: https://pepy.tech/badge/scramblery
    :target: https://pepy.tech/project/scramblery
@@ -107,3 +131,7 @@ Any kind of contribution is welcome.
    :target: https://github.com/altunenes/scramblery/actions/workflows/jekyll.yml
 .. |Build status| image:: https://ci.appveyor.com/api/projects/status/amuravq7o2afvv65?svg=true
    :target: https://ci.appveyor.com/project/altunenes/scramblery
+.. |DOI| image:: https://zenodo.org/badge/449034134.svg
+   :target: https://zenodo.org/badge/latestdoi/449034134
+.. |12x12| image:: ./docs/assets/types.png
+.. |8x8| image:: ./docs/assets/fr.png

scramblery/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "scramblery"
-version = "1.2.4"
+version = "1.2.5"
 description = ""
 authors = ["altunenes <enesaltun2@gmail.com>"]
 license = "MIT"

scramblery/scramblery/__init__.py

@@ -1,2 +1,2 @@
-__version__ = '1.2.4'
+__version__ = '1.2.5'
 from scramblery import *