# Overview

scaicha is a python script for pie chart generation. It generates a music
tag chart based on the top artists of an arbitrary [last.fm](http://last.fm) user.

The data is gathered with the help of the last.fm API and charts are drawn
using the python module [pycha](http://bitbucket.org/lgs/pycha/).

![scaidermern 6 month pie chart](http://choerbaert.org/scy/scaicha/scaidermern_6month_pie.png)


# Requirements
- python (version 2)
- pycha (shipped, also needs cairo)
- last.fm account with a sufficient number of submitted songs
- convert from imagemagick or graphicsmagick (could be omitted with the help of some small code changes)


# Installation
get the [latest version from github](http://github.com/scaidermern/scaicha/archive/master.zip) and extract it

## Linux (Debian/Ubuntu)
`apt-get install python python-cairo graphicsmagick graphicsmagick-imagemagick-compat`

notes:
- recommended python version is 2.7
- instead of *graphicsmagick graphicsmagick-imagemagick-compat* you can also install *imagemagick*

## Windows
- get [python](http://www.python.org/download/) (recommended: python 2.7)
- get [pycairo](http://www.lfd.uci.edu/~gohlke/pythonlibs/#pycairo) matching your python version

note: for the following examples to work you need to open *cmd.exe* and switch to the directory of the extracted scaicha archive.


# Usage

## standard mode
just execute the *main.py* with your *python* installation and supply at least the *-u* option including your username.

example: generate a pie chart using the default options:  
- Linux: `$ python main.py -u username`
- Windows: `python.exe main.py -u username`

there are several options to configure the behaviour of scaicha:

    -u <arg>, --user <arg>        last.fm user name (required)
    -p <arg>, --period <arg>      period of top artists (3, 6, 12; default: overall)
    -i <arg>, --ignores <arg>     comma separated list of tags to ignore, e.g. "hip hop,rap"
    -j <arg>, --join <arg>        combines a list of tag groups. groups are separated by commas, tags by colon
    -m <arg>, --minTagPerc <arg>  minimum tag percentage (default: 1.0), less occuring tags will be merged into "other tags"
    -c <arg>, --colorScheme <arg> color scheme to use (rainbow (default) or gradient)
    -b <arg>, --baseColor <arg>   base color to use (hex string or a HTML 4.0 color name)
    -l <arg>, --lighten <arg>     lighten base color by given factor (between 0.0 and 1.0)
    -r <arg>, --resize <arg>      resize image
    -s      , --score             enable score drawing
    -d      , --dump              enable dumping tags to file
    -t,     , --tagSubstitution   disable substitution of misspelled tags
    -h      , --help              print this help and exit


some examples:

use only the top artists from the past three months:  
`$ python main.py -u KarlKartoffel -p 3`

define some tags to ignore:
`$ python main.py -u WilliamKidd -i "hip hop,french"`

combine some tags, here: combine 'classic rock' and 'hard rock' into 'rock':  
`$ python main.py -u CaptainFarell -j "rock:classic rock:hard rock"`  
combine even more tags (note the usage of ':' and ','):  
`$ python main.py -u CaptainFarell -j "rock:classic rock:hard rock,metal:heavy metal:power metal"`  
you can even create new tags or rename existing ones if you like:  
`$ python main.py -u CaptainFarell -j "good stuff:rock:metal,bad stuff:hiphop:rap,worst crap ever:indie"`

draw a color gradient instead of the default rainbow colors:  
`$ python main.py -u Pferdinand -c gradient`

use another base color:  
`$ python main.py -u AverageJoe -b "#7d00ff"`  
`$ python main.py -u JohnSmith -b maroon`

lighten base color slightly:  
`$ python main.py -u AaronAronsen -l 0.3`

note: all parameters can be combined


## CGI mode
- enable CGI at your webserver
- copy `scaicha.py`, `main.py` and `settings.py` in your CGI directory
- set `CGI` to `True` in `settings.py`
- make sure your webserver is able to create new files inside the CGI directory in order to use the cache
- place the `cgi.html` document in the webserver's html directory and adapt the location of `main.py` in the form
- open `cgi.html` in your browser

note: the CGI mode lacks proper testing, use at your own risk


## License
[GPL v3](http://www.gnu.org/licenses/gpl.html)
(c) [Alexander Heinlein](http://choerbaert.org), [Deamon Hell](http://www.last.fm/user/Daemon_Hell)