The Cm2 Package for Cm1 CellExplorer
------------------------------------

The Cm2 packages are derived from the Cm2 MembraneEditor project. Please be aware that the included source files do NOT represent 
clones of the original Cm2 package. Some are clones, but some are (slightly) changed to meet the requirements of the CellExplorer.
Anyway, the original class structure of Cm2 is maintained to ease the maintenance work. It is only extended by one additional 
class folder called "external". Unique files which are exclusively found in Cm1, are found in the subpackage "cm1special".

These classes are needed to enable the MembraneMapping; the mapping of PDB files generated with Cm2 onto the surfaces of the cell
components. By using these classes, 2D textures are generated and mapped onto the surface of cell components and it is possible
to map the 3d structure of membranes onto the cell component's surface.

To use this functionality, you have to use the developer edition (switch to developer edition in CM1_CONSTANTS:
 public final static int EDITION = EDITIONS.DEVELOPER_EDITION;
Please use Cm2 to generate a membrane in PDB format and use the PDB Properties Dialog and activate the "Reverse Parsing" 
functionality. Otherwise, Cm1 will not be able to differentiate between single molecules and the whole membrane will be mapped
as a protein onto the cell component's surface. 

28.05.2013 Bjoern Sommer


Original German Text from Tim Dingersen according the classes of the Cm2 Package
--------------------------------------------------------------------------------

Moinsen!

Hier ist nun das berchtigte Bundle an Klassen, die euch aus einem pdb-file ein 3D- fhiges Objekt und mehr schnitzen sollen.
Ich habe dafr einige Klassen aus dem Cm2.1 genommen und fr eure Zwecke gepimpt, bzw. so automatisiert dass es nur ein minimum
an aufwand ist, diese zu verwenden.
 
Mit dem PdbReader_3D knnt ihr euch einfach ein Molecule-objekt kreieren lassen. So ein erzeugtes Object besitzt intern 
automatisch alle vorraussetzungen zur behandlung im 3d-space; Darstellungsnderungen sowie ausrichtung knnen und 
sollten bequem und direkt ber die methoden geregelt werden.
Das einzige was ihr anfangs machen msst, ist die Molekl-eigene BranchGroup (getBranchGroup()) in euer universum
einfgen (Bitte nicht das shape oder die Transformgroup, sonst funzt das nich...)!!!!!!

Hier ein paar Einstellungen, die ihr auf jeden Fall vornehmen msst, bevor ihr irgendetwas macht: 
Global in der Klasse Settings:

public static void setJ3D_Angstrom_Scale(float angstrom_Scale)
	Alle Werte sind in angstrom gemessen und mssen auch so eingegeben werden. Falls euer System anders ist, knnt ihr
	hier den Scale einstellen, in dem dann dargestellt wird. 

setUAMUFile(File file)
	Hier gebt bitte den pfad des unified_atomic_mass_units.txt files an, am besten packt ihr's in den workspace zu den anderen sachen.
	Dieses file wird bentigt, um die Atome berechnen zu knnen.
	
Alle anderen Settings sind optional...


Zum effizienteren zugreifen werden beim einlesen eines files die pdb-inhalte automatisch global abgelegt (fr jedes unterschiedliche file
je einmal). Um den Speicher bei ggf. sehr langem benutzen einer Programminstanz nicht kirre zu machen, solltet ihr dies beim entfernen
bercksichtigen. Solltet ihr das letzte Object eines Typs entfernt haben, lscht dessen Daten mit 
"Settings.storeRawPdbData(String absoluter pfad,null)" aus dem storage. Entfernt ihr alle(!) molekle, z.b. beim neuladen, ruft einfach
"Settings.clearRawData()" auf... 


#####     Hier eine bersicht ber die Klassen und jeweils die wichtigsten methoden:     #####

--PdbReader_3D--
 
public Molecule_3D readMolecule(File file, int modelnumber)
	Gibt euch ein besagtes Molecule-Objekt ohne irgendwelche Zwischenschritte. Das Objekt wird automatisch mit allen Daten quasi
	"tischfertig" geliefert... Als modelnummer 0 angeben, es sei denn das file besitzt mehrere Models und ihr wollt ein 
	spezielles davon verwenden..
	
	
	
!Die folgenden Methoden knnt ihr gebrauchen, wenn ihr inhaltlich mehr mit den pdb's machen wollt...!	

public String[] readFile(File file)
	Gibt euch den (kompletten) pdb inhalt zurck;jeder String in der Liste ist eine unvernderte Zeile aus dem File
	
	
	
public PdbAttributes readAttributes(File file)
	Erzeugt ein PdbAttributes-Objekt, welches ein paar headerinfos ber das Molekl enthlt.
	Sinnvoll um effizient an infos zu kommen ohne das ganze Ding aufwndig zu parsen. 
	Gut zu gebrauchen falls ihr z.B. im Filechooser oder menu properties ber noch nicht eingelesene pdb's
	anzeigen wollt..
	Sollte bereits ein Moleculeobject vorhanden sein, dann knnen die Infos besser direkt daraus gelesen werden...
	
	
	
public String[] readModel(String[] strings, int modelnumber)
	Returnt nur die (unvernderten) TOM/HETATM/TER - Zeilen des angegebenen Models
	
	
	
public boolean checkForModels(File file)
	Guckt, ob das file mit Models versehen ist
	
	
	
public String[] readSection(File file, String tag)
	Returnt nur die (unvernderten) Zeilen einer Speziellen Sektion mit entsprechendem Tag (z.B. SOURCE, TITLE, MODRES, HETATM,...)





--Molecule_3D--


public BranchGroup getBranchGroup()
	Hiermit kriegt ihr die BranchGroup, die ihr nur in das universe adden msst.
	
	
public void setPosition(Point3f newpoint)
	Setzt die position. Bitte in angstrom werten!
	
	
public void setRotationMatrix(Matrix3f rotationMatrix)
	Setzt die aktuelle rotation des objektes
	
	
public void move()
	Bewegt das molekle auf seine aktuelle Position/Rotation im 3D-space


public void setAtomsVisible(boolean b)
	Schalten die atomare Darstellungsweise an oder aus. Dies kann bei nicht-highend rechnern schonmal ein weilchen kosten...


public void setColor(Color color)
	Verndert die Farbe des Objektes (im shape-darstellungsmodus). Standardmssig ist eine zufallsfarbe
	gesetzt.
	
	
public Molecule_3D copy(boolean cloneAlignment) 
	Erzeugt eine kopie des objektes. Damit mssen mehrere gleiche molekle nicht immer neu eingelesen werden.
	Mit cloneAlignment wird ebenfalls die position/rotation kopiert, andernfalls befindet es sich am nullpunkt.
	Neu geklonte molekle wollen allerdings noch ins universe eingebaut werden..



public Point3f[] getAlignedTrianglePoints()
	Returnt die (relativ zur position/rotation ausgerichteten) dreieckspunkte(wenn der j3d-Angstrom-scale verndert wurde, dann
	sind diese skaliert!!!!!!!!)
	

public Atom[] getAtoms(boolean aligned, boolean copy) 
	Returnt die Atome! Aligned bedeutet, dass diese relativ zur position/rotation ausgerichtet sind, ansonsten bleiben
	sie unrotiert; Copy bedeutet, dass bei Bedarf eine kopie der Liste zurckgegeben wird.
	Die Atome haben Angstrom-werte!!!!
	
	
public Point3f getUpper/Lower(boolean scaledToAngstrom) 
	Gibt die beidem extrema der BoundingBox aus (mit atomabstnden einberechnet).
	ScaledToAngstrom scaliert die punkte auf angstrom, sonst gibt's den internen massstab...





--IntersectManager--

Die kollisionsabfrage funzt brigens auch mit Moleklen, die nicht im 3D-space eingefgt wurden.
Orientieren tut sie sich an der gesetzten position/rotation. So kann man vorm adden gucken, ob's passt...

public boolean intercectsMoleculeMoleculesVector(Molecule_3D mol, Vector<Molecule_3D> molecules, boolean breakAfterFirstHit)
	Testet das bergebene Molekl gegen eine Liste anderer Molekle (kann ruhig auch das zu testende 
	enthalten, wird aussortiert) auf kollisionen. Die kriterien einer Kollision (Atomar und/oder Mesh) 
	knnen global in der Settings-Klasse jederzeit verndert werden.
	Mit dem "breakAfterFirstHit" boolean kann angegeben werden, ob die kollisionsabfrage bereits nach dem ersten treffer true
	returnt, um rechenzeit zu sparen. Will man allerdings alle Kollisionen wissen, muss dieser auf false stehen...
			

public Molecule_3D[] getCollisionObjects()
	Gibt die kollidierten Molekle des letzten tests aus (sofern "breakAfterFirstHit" nicht gewhlt wurde)



--Settings--
	Hier knnt ihr globale Einstellungen vornehmen, z.B. zur przision des parsens oder zur kollisionsabfrage.
	Beachtet dass die Einstellungen bzgl. des readers nur zuknftig gelesene objekte betreffen. Die kollisionssettings
	knnen dagegen on-the-fly verndert werden
	
	
	
--MyToolkit--
	Hier knnt ihr auf einige ntzliche Methoden zurckgreifen, vor allem auch bzgl. Matrizen- und Punkttransformation.
	Auch diverse File-methoden oder eine mglichkeit, euch zufallsfarben fr die molekle generieren zu lassen etc...



--Atom--
	Objekt, dass ein atom reprsentiert. Ihr erhaltet die atome eines molekls mit der getAtoms-methode. Aus den atomen
	lassen sich neben den koordinaten auch alle informationen, die im pdb-eintrag dazu waren, auslesen


--Viewer_Ultralight--
	Ist nur nen testviewer, mit dem ich diese Klassen ausserhalb von Cm2.1 getestet hab.
	
--Atom_Creator_3D--
	Erzeugt die visuellen elemente fr die Atomare darstellung. Sollte fr euch uninterressant sein...
	
	
Wendet euch bei fragen einfach an mich, dem dackelnose@gmx.net  ;) 	
Ich berarbeite die Atomare darstellung noch ein wenig, aber falls ich euch ein update schicke, dann so dass ihr an 
bestehendem nix ndern msst...

Dann mal viel Erfolg, wa? 
Der Timmey!!!

	
	
	
	
Nachtrag:
---------

Hallo nochmal!!!

Hier schicke ich euch den Rest, damit ihr aus einer pdb-membran oder aus einer .cm2 membran
ein ganzes membranmodell einlesen knnt.

Bitte verwendet dafr nur membranen, die mit der aktuellen cm2-version generiert wurden, andererseits
fehlen die ntigen informationen in den files...
In einer membran werden inzwischen nmlich die rohdaten von jedem beteiligten molekl-pdb (jeweils einmal
pro typ) mit abgelegt, um reverses parsen zu ermglichen und die membranen unabhngig von lokalen pdb's
zu machen...


Eine membran wird also als ein MembraneModel gehandhabt, welches ihr euch einlesen knnt... 

Wollt ihr es aus einer pdb-membran wiederherstellen, macht folgendes:

ReversePDBParser myparser = new ReversePDBParser(File tempDir);
//wobei tempDir euer temporres verzeichnis sein sollte.. Ihr knnt auch null bergeben, dann
//wird das user.home benutzt...
MembraneModel newmodel = myparser.restoreMembraneModelFromPdbFile(File pdbMembraneFile)
//das war's schon. Dauert je nach dem ein paar sekndchen...


Solltet ihr nicht weiterverarbeitete membranen einlesen wollen, knnt ihr sie auch direkt aus .cm2-membranen
im xml format einlesen:

MembraneXmlReader myReader= new MembraneXmlReader(StatusDialog dialog);
//Ihr knnt einen neuen Statusdialog mitgeben um einen ladedialog anzuzeigen oder null bergeben...

myReader.readMembrane( File cm2MembraneFile);
MembraneModel newmodel =myReader.getResultingMembraneModel()





Aus dem MembraneModel knnt ihr dann mit 

public Molecule_3D[] getAllMolecules()

alle molekle auslesen und in einer Schleife wie gehabt in euer universe einbauen...
Vergesst nicht anschliessend einmal move() auf die molekle aufzurufen, damit sie an ihre
vorgegebene position wandern...

Ihr knnt ihr die molekle in Protein_3D und Lipid_3D unterscheiden...Jedes Molecule_3D(deren superklasse)
ist entweder Protein oder Lipid.
Ausserdem sind die extrazellulren und intrazellulren lipide in getrennten listen. Ihr knnt daher
auch diese methoden verwenden, wenn ihr sie unterscheiden wollt:

public Vector<Protein_3D> getAllProteins()
public Vector<Lipid_3D> getAllLipidsExtra()
public Vector<Lipid_3D> getAllLipidsIntra()


Es gibt noch dutzende andere zugriffsmethoden, auf die ich aber hier nicht eingehe. Seht ihr schon....

hnlich wie bei den molecules knnt ihr auch beim membraneModel ber diverse getter 
an metainfos wie TITLE, SOURCE usw kommen. 
Vor allem public Dimension getSize() ist dabei interressant (angtrom mae)






Neu am pdbReader_3D ist jetzt, dass man wegen der unterscheidung halt entweder

public Molecule_3D readProtein(File file, int modelnumber,
			Vector<String> alteredAtoms) 

oder

public Molecule_3D readLipid(File file, int modelnumber,
			Vector<String> alteredAtoms) 


verwenden muss. alteredAtoms kann und sollte dabei null sein!!








btw: alles was mit ExampleLipid/ SampleLipid/ Lipidtemplate zu tun hat bezieht sich
auf die lipidinstanzen aus der seitlichen Liste im Cm2. Ignoriert die einfach!!!





Achso: Falls ihrs braucht: Im Molecule_3D hat sich die methode zur darstellungsweise gendert;
Sie heisst jetzt 
setRenderMode(int renderMode)
und ihr knnt ihr einen von den vier konstanten bergeben die ihr im Molecule_3D findet:

public static final int RENDER_MODE_POLYGON
public static final int RENDER_MODE_VAN_DER_WAALS 
public static final int RENDER_MODE_COLORED_STICKS
public static final int RENDER_MODE_REDUCED_VAN_DER_WAALS_AND_WHITE_STICKS 

Die colored Sticks beintrchtigen die framerate brigens kaum, sobald sie einmal eingefgt sind


So, nun aber...
Alles Gute,
Timmy