------------------------------------------------------------------------------
--------------------CELLmicrocosmos 1 CellExplorer (CmCX)---------------------
-----------------CELLmicrocosmos 4 PathwayIntegration (CmPI)------------------
--------------------------------------------------------------------README.txt



Welcome to the CELLmicrocosmos 1 CellExplorer (CmCX)/CELLmicrocosmos 4 
PathwayIntegration (CmPI) package. This tool combines 3D stereoscopic cell 
visualization with Bioinformatics approaches used to predict the localization
of genes or proteins in a specific scenario.

-------Content------
- What is it?      -
- Copyright Notice -
- Start            -
- Documentation    -
- Navigation       -
- Requirements     -
- Contact          -
- How to cite      -
- Acknowledgements -
--------------------



What is it?
===========

The CellExplorer (CmCX) is a Java7/Java3D-based tool for exploring cell models.
Their exist different cell models for the CellExplorer, some of them are 
directly bundled with the program. Different navigation modi exist which can be
used to fly through the cell environment. In addition, CmCX supports different
stereoscopy options. There are, e.g., options for simple side-by-side stereo 
which is compatible to 3D TVs, and there is also the option to use professional
stereoscopy in case a Quad-Buffered card - such as the NVIDIA Quadro graphics -
are available. The CellExplorer is moreover the base for CEEE, the Educational 
Edition. By now, only a German version is available, coming with information 
pages for all cell components. More information you will find here:
http://ceee.cellmicrocosmos.org
If you are interested in this particular project, please contact us. See the 
contact info below.

The PathwayIntegration (CmPI) is a complex extension of the CellExplorer. It can 
be used to localize protein- or gene-related data in the cell environment. 
Different publications exist on this topic, please see the corresponding section
below. It is possible to enter just a list of proteins/genes, and/or to manually 
create networks with the 2D Viewer, and/or to import data in SBML, GraphML or
StringDB format. 
For the localization, 2 basic data providers are used:
DAWIS-M.D. (https://agbi.techfak.uni-bielefeld.de/DAWISMD/), integrating 
different biomedical databases, and
ANDCell (http://www.pbiosoft.com), integrating PubMed-based text mining data.
The localization is supported by the Subcellular Localization Charts. The 
localizations can be visualized by using the charts, the 2D Viewer, as well as 
the 3D Viewer. In this case, a localization scenario is illustrated in 3D space 
by combining the protein/gene-related nodes with the cell components as a 3D 
network.



Copyright Notice
================
 
Copyright (C) 2005-2015 The CELLmicrocosmos 1/4 Development Team
                        (Bj�rn Sommer et al., Bielefeld University)
Copyright (C) 2015 		Bj�rn Sommer, Monash University
                        
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
 
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
 
You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Please see the LICENSE for the complete text and please see the How to cite
section for relevant publications.

PLEASE SEE THE ATTACHED PDF COPYRIGHT.PDF FOR MORE INFORMATION.



Start
=====

For starting the CellExplorer/PathwayIntegration, just execture:
 Cm1_2_CmPI_buildDDMMYYYY.jar

Moreover, there are actually two versions, one for Java 7 and one for Java 8.
This is usually only relevant in case you want to create your own layout
algorithms and import them into CmPI, because in this case the algorithms
are directly compiled by CmPI.
 
Just remember that there is also the Java Webstart application located at
 http://Cm1.CELLmicrocosmos.org
 http://Cm4.CELLmicrocosmos.org


 
Documentation
=============

The whole help files are bundled with the CellExplorer/PathwayIntegration.
The theoretical background and detailed application cases are discussed in our
publication found in the How to cite section.



Navigation
==========

Basics
------
In order to navigate through the visualized cell in the CellExplorer,
the user may move the virtual camera. The camera is characterized
by a viewing position and a direction, as well as a focal length (zoom
factor). Each of these can be modified through user input on mouse 
and keyboard. Controls were designed in a way, that either sole mouse 
OR sole keyboard are sufficient, albeit simultaneous use of both is 
highly recommended.

Camera Manipulation
-------------------
For navigating inside the CellExplorer with the keyboard, the arrow
keys, as well as [W],[A],[S],[D] are used for camera manipulation. 
They are often used in combination with [CTRL]. 
The precise action that is associated with these inputs, depends on 
the active navigation mode. There are currently three different modes
to distinguish. 

*Floating mode* is the initial state after launch. The cursor is free to
move around on screen for interaction with nodes and components. The
camera is moved and turned around in the local (camera) coordinate 
system. This movement is independent from any object in the cell.
Floating mode is kind of an initial mode from where to switch into 
and from one of the two other more specialized modes.

Holding down [SHIFT] or activating [CAPS-LOCK] enables *Flight mode*.
This mode is very similar to floating mode, as it moves the camera
vessel-like in the local coordinate system. The key difference is the
fact, that the cursor is locked in the middle of the 3D-View. Although
this makes a GUI-interaction impossible, it enables a more intuitive
navigation, as the camera can be turned around with the mouse.

If there is a picked object, the user can bind to it and switch to 
*Object-bound mode*. In this mode, there is a specific object, the
camera moves around. The user can no more navigate in camera local
coordinates but moves along longitude and altitude of the bound
object. Height above the object and tilt from the perpendicular 
vector can be manipulated.

The camera view may be reset via context menu or pressing [h].

Picking
-------
Interaction with cell components or pathway nodes is triggered via 
mouse or the left-click-counterpart [SPACE]. By pressing the left mouse 
button or [SPACE]-down, picking is activated. In this state, the user
can select one of the objects under the cursor using the mouse wheel
or [+],[-] keys. On release of either space or left mouse button, the
selected object is picked. Picking an object displays information about
it in the info panel and makes it usable for object bound mode.

While picking, usually the nearest object is preselected. If the former
picked object is a node and this node happens to be under the cursor,
it is preferred over the nearest cell component. This makes it easier to 
show the context menu for a node, as they are often behind larger
cell components.

Zoom
----
Focal length can be changed via [+],[-] or mouse wheel (when picking
is not active). Zoom may be reset to the original setting via context
menu or [r].
 


Requirements
============

The Webstart version of CmPI can be directly started at 
 http://Cm4.CELLmicrocosmos.org
This was tested on different Windows, Linux and MAC systems.

Webstart version
----------------
Please note that the Webstart Version is not the actual version.
It is planned to update this also with the actual version. It is recommended
to use the Standalone Version.
- Oracle Java 6</li>
- Java3D is automatically downloaded and installed 
  when starting the webstart application</li>
- OS: 
  Windows XP, Vista, 7
  Linux, e.g. Ubuntu 10.04 LTS
- Please refer to the instructions at 
   http://forum.CELLmicrocosmos.org
  if you have problems installing CmME.

Standalone version
------------------
- Oracle Java 7-8
- JogAmp Java 3D, version 1.6.X
   http://forum.jogamp.org/java3d-f3728156.html
- OS:
  Windows XP, Vista, 7
  Mac OS X
  Linux, e.g. Ubuntu 14.04 LTS
- Please refer to the instructions at the 
   http://forum.CELLmicrocosmos.org
  if you have problems installing CmCX/CmPI.



Contact
=======

If you have questions, remarks, critics or bug fixes, please post them
in our forum at
 http://forum.CELLmicrocosmos.org
or contact us directly via email:
 bjoern@CELLmicrocosmos.org
To stay in touch with our latest releases, you can also add your name
to our mailing list at
 http://Cm4.CELLmicrocosmos.org



How to cite
===========

Conference Articles
-------------------
Sommer, Bj�rn; Wang, Stephen Jia; Xu, Lifeng; Chen, Ming; Schreiber, Falk. 
Hybrid-Dimensional Visualization and Interaction - Integrating 2D and 3D 
Visualization with Semi-Immersive Navigation Techniques. In Proceedings of 
IEEE International Symposium on Big Data Visual Analytics. IEEE, 2015. 
http://dx.doi.org/10.1109/BDVA.2015.7314295

Sommer, Bj�rn; K�nsem�ller, J�rn; Sand, Norbert; Husemann, Arne; Rumming, 
Madis; Kormeier, Benjamin: CELLmicrocosmos 4.1: An interactive approach to 
Integrating Spatially Localized Metabolic Networks into a Virtual 3D Cell 
Environment. In Fred, Ana; Filipe, Joaquim; Gamboa, Hugo (eds.): Proceedings 
of Bioinformatics 2010: 90-95, 2010, ISBN 978-989-674-019-1. 
http://www.bioinformatics.biostec.org
Download at the BIOSTEC 2010 section.

Book Chapters
-------------
Sommer, Bj�rn: Network Analysis and Integration in a Virtual Cell Environment. 
In Ming Chen, Ralf Hofest�dt (eds): Approaches in Integrative Bioinformatics - 
Towards the Virtual Cell, ISBN:3642412807, Springer Verlag, 275-296, 2014. 
Online Chapter: DOI: 10.1007/978-3-642-41281-3_10

Journal Articles
----------------
Sommer, Bj�rn; Kormeier, Benjamin; Demenkov, Pavel S.; Arrigo, Patrizio; Hippe, 
Klaus; Ates, �zg�r; Kochetov, Alexey V.; Ivanisenko, Vladimir A.; Kolchanov, 
Nikolay A.; Hofest�dt, Ralf: Subcellular Localization Charts: A new visual 
Methodology for the semi-automatic Localization of protein-related Data Sets. 
Journal of Bioinformatics and Computational Biology, 11(1):134005, 2013. 
Online Journal: 
http://www.worldscientific.com/doi/abs/10.1142/S0219720013400052

Sommer, Bj�rn; Tiys, Evgeny S.; Kormeier, Benjamin; Hippe, Klaus;
Janowski, Sebastian J.; Ivanisenko, Timofey V.; Bragin, Anatoly O. ; Arrigo, 
Patrizio; Demenkov, Pavel S.; Kochetov, Alexey V.; Ivanisenko, Vladimir A.; 
Kolchanov, Nikolay A.; Hofest�dt, Ralf: Visualization and Analysis of a Cardio 
Vascular Disease- and MUPP1-related Biological Network combining Text Mining 
and Data Warehouse Approaches. Journal of Integrative Bioinformatics, 7(1):148, 
2010. Online Journal: 
http://journal.imbio.de/index.php?paper_id=148

Website
-------
http://Cm4.CELLmicrocosmos.org



Acknowledgements
================

A large number of people have contributed to this work by development, critics, 
hints or remarks. Indeed, the first version of this software was developed 
under my supervision by a number of master students at Bielefeld University 
years ago. This version was revised over the years in a number of projects. 

A list of all those people involved in this work you will find at
 http://team.CELLmicrocosmos.org
Thanks to all of you!

Additional thanks go to the numerous developers of packages included in this 
software. Please see the COPYRIGHT.PDF for more information.

For the financial support, I want to thank the Deutsche Forschungsgesellschaft 
(DFG) Graduate College Bioinformatics (GK635) and my previous PhD supervisor 
Prof. Ralf Hofest�dt from the Bio-/Medical Department of Bielefeld University.

For more information about the CELLmicrocosmos project, further developments
and our vision, just have a look at our website.

Bj�rn Sommer, Bielefeld 22.11.2015