VisualSense Files

=================================================================
== VisualSense. Interactive coordinated data visualization ==
=================================================================
version 0.9.4

NUS-IDMI-MMALab in collaboration with UCSD
Original developper: Bertrand Grandgeorge
Graphic designer: Ong Kian Peng (aka Bin)

DESCRIPTION
-----------
VisualSense was developed to serve as an analysis tool for textual and numerical data extracted from image analysis of artwork from different cultures and influences.
The data structure required to feed the software is actually generic and can be used to display anything as long as it respect the data format.


INSTALLATION
------------
- This software runs on Adobe AIR environment. Download and install from: http://get.adobe.com/air/
- Double click on the VisualSense.air package and install to the directory of your choice.


GETTING STARTED
---------------
- Run the application and open select 'Open database...' in the file menu.
- Browse to the application folder and select the 'sample.db' database file
- The software will display the path to the database file and the assume directory of the images files. The image directory can be changed from the file menu 'Change image directory...' but the assumed directory is fine for this example
- Next click the 'Add graph' button in the graphMaker window. A new line appear which controls the settings for each graph. More graphs can be added at any time.
- Select the graph type, change the size and position, and other options if necessary
- Choose the statistic to display on each axis (respecting the limitations below)
- press the update graphs button to plot the graph with the updated settings


GRAPH TYPES
-----------
Each statistic has a type (int, string, float) visible in a tooltip while choosing the axis. Each graph works with a different type of stats:
- Bar chart   : 1 dimension with int or string statistic
- Bubble chart: 3 dimensions with numeric statistics and radius postive or null
- Histogram   : 1 dimension numeric statistic
- Pie chart   : 1 dimension numeric statistic
- Scatter plot: 2 dimensions numeric statistics


COORDINATED SELECTION
---------------------
- Select a dot/bar/sector in a chart and see the selection change in all graphs displayed in the canvas
- Usual OS-specific selection modes are available to select a range or several objects


SAVE A PICTURE OF THE CANVAS
----------------------------
From the file menu, choose 'Save graphs window...' to generate an PNG image file of the canvas with a resolution of 150dpi.
Note: graphs larger than 1500 pixels (wide or tall) may crash the application depending on the available memory of your computer

SAVE / LOAD GRAPHS LAYOUT
------------------------
From the file menu, choose the 'Save graphs layout' to create a xml description file of your visualization.
The same file can be loaded (with the relevant dataset already loaded) to retrieve your saved layout.
Note: for safety, displaying of image is deactivated (for concerned charts)


DATA STRUCTURE FOR CSV IMPORT
-----------------------------
The program works with a sqlite database file that may be generated, and offers the possibility to import data from a CSV file into a new database. The CSV is required to have the following structure:
- 1st line, the statistic names
- 2nd line, the statistic types, either int, string or float
- The first column of the first line HAS TO BE 'filename' in lower case
- each subsequent line: the values corresponding to each column

Example:
filename,1_number,2_Year,3_Portrait,6_bw/color,7_drawing/photo,8_race,9_Male/Female,10_Baby,11_Mean
string,int,int,string,string,int,string,string,string,string,int,float
1101230303_400.jpg,1,1923,portrait 1 pers.,B&W,drawing,caucasian,Male,0,181.023
1101230310_400.jpg,2,1923,portrait 1 pers.,B&W,drawing,asian,Male,0,184.813

To import select 'Import spreadsheet...' in the file menu, wait for the import to finish, and set the image directory ('Change image directory' from the file menu)


IMAGE SIZES AND FORMAT
----------------------
The application accepts Jpeg, Gif or Png image formats.
For better performance consider resizing the picture to a smaller size if you want to use the display image picture. Usually an image size of around 100-150 pixels is a good choice.

The size can be reduced by changing the zoom factor in the interface. A decimal value between 0 and 1 will reduce the image size, and a larger value will increase it. Zoom factor larger than 1 is not recommended as it will decrease the quality of the picture and create pixelisation.


STATS (SCATTER PLOT)
--------------------
Currently only available for scatter plots, this features displays 3 horizontal lines calculated according to the mean value on the Y axis (middle, thicker bar), and standard deviation on the Y axis (2 other horizontal bars).
The 2 thiner horizontal bars are positionned on the Y axis as: mean-standard_deviation (below the average) and mean+standard_deviation (above the average).
This represent the range where most of the data is concentrated.


ADVANCED SETTINGS (At user's own risk)
-----------------
Advanced settings are available in the config.xml file: numObjLimit and exportDpi. Use these settings with care as higher values might crash the applications.
On OSX, The config.xml file is the Contents/Resources folder (view package contents from OSX).
numObjLimit (default = 800) sets the maximum number of image displayed in a graph.
exportDpi (default = 300) sets the DPI value for the resolution of exported images. Other typical values are: 72 (screen resolution), 150, 300. Note that the output resolution of the images will depend on the zoom Factor: if exportDpi=150 and zoomFactor is 0.5, images will be displayed at almost maximum resolution (72/0.5~=150).


=================================================================
VERSION HISTORY

v 0.9.4 graphLayout import -- This version
	- Changed graphLayout export format
	- Added graphLayout import feature
	- Externalized list of stylesheet in themes/stylesList.xml for easy configuration of new stylesheets
	- Some refactoring

v 0.9.3 AIR 2.0
	- Upgraded to Flex 4.1 SDK (with support for AIR 2.0)
	- Improved About dialog box
	- Added lots of comments
	- Did some cleanup and refactoring
v 0.9.2 Windows-compatible
	- Windows tested
	- Changed menus architecture
	- Numeric inputs with surface validation
	- Bug fixes
v 0.9.1 Mac tested version


=================================================================
Known issues
[Bug #728] Bubble graph doesn't normalize the radius value, forcing the user to manually put an adapted zoom factor.