Package: skin-tone-classifier
An easy-to-use library for skin tone classification.This can be used to detectfaceorskin areain the specified images.
The detected skin tones are then classified into the specified color categories.
The library finally generates results to report the detected faces (if any),
dominant skin tones and color categories.Check out theChangelogfor the latest updates.If you find this project helpful, please
considergiving it a star⭐.It would be a great encouragement
for me!Table of ContentsVideo tutorialsPlaylist1. How to install Python andstone2. Usestonein GUI mode3. Usestonein CLI mode4. Usestonein Python scriptsInstallationInstall from pipInstall the CLI mode onlyInstall the CLI mode and the GUI modeInstall from sourceHOW TO USEQuick StartUsestonein a GUIUsestonein command line interface (CLI)Interpretation of the tableDetailed UsageUse Cases1. Process multiple images2. Specify color categories3. Specify category labels4. Specify output folder5. Store report images for debugging6. Specify the types of the input image(s)7. Convert thecolorimages toblack/whiteimages8. Tune parameters of face detection9. Multiprocessing settings10. Used as a library by importing into other projectsCitationContributingDisclaimerVideo tutorialsPlease visit the following video tutorials if you have no programming background or are unfamiliar with how to use Python and this library 💖PlaylistClick here to show more.1. How to install Python andstone2. Usestonein GUI mode3. Usestonein CLI mode4. Usestonein Python scriptsPlease refer to this notebookfor more information.More videos are coming soon...Installation[!TIP]Since v1.2.3, we have made the GUI modeoptional.Install from pipInstall the CLI mode onlypipinstallskin-tone-classifier--upgradeIt is useful for users who want to use this library in non-GUI environments, e.g., servers or.Install the CLI mode and the GUI modepipinstallskin-tone-classifier[all]--upgradeIt is useful for users who are not familiar with the command line interface and want to use the GUI mode.Install from sourcegitclonegit@github.com:ChenglongMa/SkinToneClassifier.gitcdSkinToneClassifier
pipinstall-e.--verbose[!TIP]If you encounter the following problem:ImportError: DLL load failed while importing _core: The specified module could not be foundPlease download and installVisual C++ Redistributableathere.Then this error will be gone.HOW TO USE[!TIP]You can combine the following documents,the video tutorials aboveand the running examplesto understand the usage of this library more intuitively.Quick StartUsestonein a GUI✨ Since v1.2.0, we have provided a GUI version ofstonefor users who are not familiar with the command line
interface.Instead of typing commands in the terminal, you can use the config GUI ofstoneto process the images.Steps:Open the terminal that can runstone(e.g.,PowerShellin Windows orTerminalin macOS).Typestone(without any parameters) orstone --guiand pressEnterto open the GUI.Specify the parameters in each tab.Click theStartbutton to start processing the images.Hopefully, this can make it easier for you to usestone🍻![!TIP]It is recommended to install v1.2.3+, which supports Python 3.9+.If you have installed v1.2.0, please upgrade to v1.2.3+ by runningpip install skin-tone-classifier[all] --upgradeIf you encounter the following problem:This program needs access to the screen. Please run with a Framework
build of python, and only when you are logged in on the main display
of your Mac.Please launch the GUI by runningpythonw -m stonein the terminal.
References:stackoverflowpython-using-macUsestonein command line interface (CLI)To detect the skin tone in a portrait, e.g.,Just run:stone-i/path/to/demo.png--debugThen, you can find the processed image in./debug/color/faces_1folder, e.g.,In this image, from left to right you can find the following information:detected face with a label (Face 1) enclosed by a rectangle.dominant colors.The number of colors depends on settings (default is 2), and their sizes depend on their proportion.specified color palette and the target label is enclosed by a rectangle.you can find a summary text at the bottom.Furthermore, there will be a report file namedresult.csvwhich contains more detailed information, e.g.,fileimage typeface iddominant 1percent 1dominant 2percent 2skin tonetone labelaccuracy(0-100)demo.pngcolor1#C996760.67#8053410.33#9D7A54CF86.27Interpretation of the tablefile: the filename of the processed image.NB: The filename pattern of report image is<file>-<face id>.<extension>image type: the type of the processed image, i.e.,colororbw(black/white).face id: the id of the detected face, which matches the reported image.NAmeans no face has been detected.dominant n: then-th dominant color of the detected face.percent n: the percentage of then-th dominant color, (0~1.0).skin tone: the skin tone category of the detected face.tone label: thelabelof skin tone category of the detected face.accuracy: the accuracy of the skin tone category of the detected face, (0~100). The larger, the better.Detailed UsageTo see the usage and parameters, run:stone-h(or--help)Output in console:usage: stone [-h] [-i IMAGE FILENAME [IMAGE FILENAME ...]] [-r] [-t IMAGE TYPE] [-p PALETTE [PALETTE ...]]
             [-l LABELS [LABELS ...]] [-d] [-bw] [-o DIRECTORY] [--n_workers WORKERS] [--n_colors COLORS]
             [--new_width WIDTH] [--scale SCALE] [--min_nbrs NEIGHBORS] [--min_size WIDTH [HEIGHT ...]]
             [--threshold THRESHOLD] [-v]

Skin Tone Classifier

options:
  -h, --help            show this help message and exit
  -i IMAGE FILENAME [IMAGE FILENAME ...], --images IMAGE FILENAME [IMAGE FILENAME ...]
                        Image filename(s) or URLs to process;
                        Supports multiple values separated by space, e.g., "a.jpg b.png";
                        Supports directory or file name(s), e.g., "./path/to/images/ a.jpg";
                        Supports URL(s), e.g., "https://example.com/images/pic.jpg" since v1.1.0+.
                        The app will search all images in current directory in default.
  -r, --recursive       Whether to search images recursively in the specified directory.
  -t IMAGE TYPE, --image_type IMAGE TYPE
                        Specify whether the input image(s) is/are colored or black/white.
                        Valid choices are: "auto", "color" or "bw",
                        Defaults to "auto", which will be detected automatically.
  -p PALETTE [PALETTE ...], --palette PALETTE [PALETTE ...]
                        Skin tone palette;
                        Supports RGB hex value leading by "#" or RGB values separated by comma(,),
                        E.g., "-p #373028 #422811" or "-p 255,255,255 100,100,100"
  -l LABELS [LABELS ...], --labels LABELS [LABELS ...]
                        Skin tone labels; default values are the uppercase alphabet list leading by the image type ('C' for 'color'; 'B' for 'Black&White'), e.g., ['CA', 'CB', ..., 'CZ'] or ['BA', 'BB', ..., 'BZ'].
  -d, --debug           Whether to generate report images, used for debugging and verification.The report images will be saved in the './debug' directory.
  -bw, --black_white    Whether to convert the input to black/white image(s).
                        If true, the app will use the black/white palette to classify the image.
  -o DIRECTORY, --output DIRECTORY
                        The path of output file, defaults to current directory.
  --n_workers WORKERS   The number of workers to process the images, defaults to the number of CPUs in the system.
  --n_colors COLORS     CONFIG: the number of dominant colors to be extracted, defaults to 2.
  --new_width WIDTH     CONFIG: resize the images with the specified width. Negative value will be ignored, defaults to 250.
  --scale SCALE         CONFIG: how much the image size is reduced at each image scale, defaults to 1.1
  --min_nbrs NEIGHBORS  CONFIG: how many neighbors each candidate rectangle should have to retain it.
                        Higher value results in less detections but with higher quality, defaults to 5.
  --min_size WIDTH [HEIGHT ...]
                        CONFIG: minimum possible face size. Faces smaller than that are ignored, defaults to "90 90".
  --threshold THRESHOLD
                        CONFIG: what percentage of the skin area is required to identify the face, defaults to 0.15.
  -v, --version         Show the version number and exit.Use Cases1. Process multiple images1.1 Multiple filenamesstone-i(or--images)a.jpgb.pnghttps://example.com/images/pic.jpg1.2 Images in some folder(s)stone-i./path/to/images/NB: Supported image formats:.jpg, .gif, .png, .jpeg, .webp, .tif.In default (i.e.,stonewithout-ioption), the app will search images in current folder.2. Specify color categories2.1 Use HEX valuesstone-p(or--palette)#373028 #422811 #513B2ENB: Values start with'#'and are separated byspace.2.2 Use RGB tuple valuesstone-p55,48,4066,40,17251,242,243NB: Values split bycomma ',', multiple values are still separated byspace.3. Specify category labelsYou can assign the labels for the skin tone categories, for example:"CA": "#373028",
"CB": "#422811",
"CC": "#513B2E",
...To achieve this, you can use the-l(or--labels) option:3.1 Specify the labels directly usingspacesas delimiters, e.g.,stone-lABCDEFGH3.2 Specify the range of labels based on this pattern:<start><sep><end><sep><step>.Specifically,<start>: thestartlabel, can be a letter (e.g.,A) or a number (e.g.,1);<end>: theendlabel, can be a letter (e.g.,H) or a number (e.g.,8);<step>: thestepto generate the label sequence, can be a number (e.g.,2or-1),defaults to1.<sep>: theseparatorbetween<start>and<end>, can be one of these symbols:-,,,~,:,;,_.Examples:stone-lA-H-1which is equivalent tostone -l A-Handstone -l A B C D E F G H.stone-lA-H-2which is equivalent tostone -l A C E G.stone-l1-8which is equivalent tostone -l 1 2 3 4 5 6 7 8.stone-l1-8-3which is equivalent tostone -l 1 4 7.[!IMPORTANT]Please make sure the number of labels is equal to the number of colors in the palette.4. Specify output folderThe app puts the final report (result.csv) in current folder in default.To change the output folder:stone-o(or--output)./path/to/output/The output folder will be created if it does not exist.Inresult.csv, each row is showing the color information of each detected face.
If more than one faces are detected, there will be multiple rows for that image.5. Store report images for debuggingstone-d(or--debug)This option will store the report image (like the demo portrait above) in./path/to/output/debug/<image type>/faces_<n>folder,
where<image type>indicates if the image iscolororbw(black/white);<n>is the number of faces detected in the image.By default, to save storage space, the app does not store report images.Like in theresult.csvfile, there will be more than one report images if 2 or more faces were detected.6. Specify the types of the input image(s)6.1 The input are color imagesstone-t(or--image_type)color6.2 The input are black/white imagesstone-t(or--image_type)bw6.3In default, the app will detect the image type automatically, i.e.,stone-t(or--image_type)autoForcolorimages, we use thecolorpalette to detect faces:#373028 #422811 #513b2e #6f503c #81654f #9d7a54 #bea07e #e5c8a6 #e7c1b8 #f3dad6 #fbf2f3#373028#422811#513B2E#6F503C#81654F#9D7A54#BEA07E#E5C8A6#E7C1B8#F3DAD6#FBF2F3(Please refer to our paper above for more details.)Forbwimages, we use thebwpalette to detect faces:#FFFFFF #F0F0F0 #E0E0E0 #D0D0D0 #C0C0C0 #B0B0B0 #A0A0A0 #909090 #808080 #707070 #606060 #505050 #404040 #303030 #202020 #101010 #000000#FFFFFF#F0F0F0#E0E0E0#D0D0D0#C0C0C0#B0B0B0#A0A0A0#909090#808080#707070#606060#505050#404040#303030#202020#101010#000000(Please refer toLeigh, A., & Susilo, T. (2009). Is voting skin-deep? Estimating the effect of candidate ballot photographs on election
outcomes.Journal of Economic Psychology, 30(1), 61-70.for more details.)7. Convert thecolorimages toblack/whiteimagesand then do the classification usingbwpalettestone-bw(or--black_white)For example:1. Input2. Convert to black/white image3. The final report imageNB: we did not do the opposite, i.e., convertblack/whiteimages tocolorimages
because the current AI models cannot accurately "guess" the color of the skin from ablack/whiteimage.
It can further bias the analysis results.8. Tune parameters of face detectionThe rest parameters ofCONFIGare used to detect face.
Please refer tohttps://stackoverflow.com/a/20805153/8860079for detailed information.9. Multiprocessing settingsstone--n_workers<AnyPositiveInteger>Use--n_workersto specify the number of workers to process images in parallel, defaults to the number of CPUs in your
system.10. Used as a library by importing into other projectsYou can refer to the following code snippet:importstonefromjsonimportdumps# process the imageresult=stone.process(image_path,image_type,palette,*other_args,return_report_image=True)# show the report imagereport_images=result.pop("report_images")# obtain and remove the report image from the `result`face_id=1stone.show(report_images[face_id])# convert the result to jsonresult_json=dumps(result)stone.processis the main function to process the image.
It has the same parameters as the command line version.It will return adict, which contains the process result and report image(s) (if required,
i.e.,return_report_image=True).You can further usestone.showto show the report image(s).
And convert the result tojsonformat.Theresult_jsonwill be like:{"basename":"demo","extension":".png","image_type":"color","faces":[{"face_id":1,"dominant_colors":[{"color":"#C99676","percent":"0.67"},{"color":"#805341","percent":"0.33"}],"skin_tone":"#9D7A54","tone_label":"CF","accuracy":86.27}]}CitationIf you are interested in our work, please cite:@article{https://doi.org/10.1111/ssqu.13242,author={Rej\'{o}n Pi\tilde{n}a, Ren\'{e} Alejandro and Ma, Chenglong},title={Classification Algorithm for Skin Color (CASCo): A new tool to measure skin color in social science research},journal={Social Science Quarterly},volume={n/a},number={n/a},pages={},keywords={colorism, measurement, photo elicitation, racism, skin color, spectrometers},doi={https://doi.org/10.1111/ssqu.13242},url={https://onlinelibrary.wiley.com/doi/abs/10.1111/ssqu.13242},eprint={https://onlinelibrary.wiley.com/doi/pdf/10.1111/ssqu.13242},abstract={Abstract Objective A growing body of literature reveals that skin color has significant effects on people's income, health, education, and employment. However, the ways in which skin color has been measured in empirical research have been criticized for being inaccurate, if not subjective and biased. Objective Introduce an objective, automatic, accessible and customizable Classification Algorithm for Skin Color (CASCo). Methods We review the methods traditionally used to measure skin color (verbal scales, visual aids or color palettes, photo elicitation, spectrometers and image-based algorithms), noting their shortcomings. We highlight the need for a different tool to measure skin color Results We present CASCo, a (social researcher-friendly) Python library that uses face detection, skin segmentation and k-means clustering algorithms to determine the skin tone category of portraits. Conclusion After assessing the merits and shortcomings of all the methods available, we argue CASCo is well equipped to overcome most challenges and objections posed against its alternatives. While acknowledging its limitations, we contend that CASCo should complement researchers. toolkit in this area.}}Contributing👋 Welcome toSkinToneClassifier! We're excited to have your contributions. Here's how you can get involved:💡Discuss New Ideas: Have a creative idea or suggestion? Start a discussion in
theDiscussionstab to share your thoughts and
gather feedback from the community.❓Ask Questions: Got questions or need clarification on something in the repository? Feel free to open
anIssuelabeled as a "question" or participate
inDiscussions.🐛Issue a Bug: If you've identified a bug or an issue with the code, please open a
newIssuewith a clear description of the problem, steps
to reproduce it, and your environment details.✨Introduce New Features: Want to add a new feature or enhancement to the project? Fork the repository, create a
new branch, and submit aPull Requestwith your changes.
Make sure to follow our contribution guidelines.💖Funding: If you'd like to financially support the project, you can do so
bysponsoring the repository on GitHub. Your contributions help us
maintain and improve the project.DisclaimerThe images used in this project are fromFlickr-Faces-HQ Dataset (FFHQ),
which is licensed under theCreative Commons BY-NC-SA 4.0 license.Thank you for considering contributing toSkinToneClassifier.
We value your input and look forward to collaborating with you!