iCn3D Web APIs



How to use iCn3D Structure Viewer in your html page:back to top


URL parameters for the advanced interfaceback to top

ParameterBasic interface
(index.html)
Advanced interface
(full.html)
Description
mmdbidYesYesNCBI MMDB ID or PDB ID, e.g., ?mmdbid=1tup&showanno=1&show2d=1
mmtfidYesYesMMTF ID, e.g., ?mmtfid=1tup
pdbidYesYesPDB ID, e.g., ?pdbid=1tup
mmcifidYesYesmmCIF ID, e.g., ?mmcifid=1tup
giYesYesNCBI protein gi number, e.g., ?gi=827343227
cidYesYesPubChem Compound ID, e.g., ?cid=2244
alignNoYesTwo PDB IDs or MMDB IDs for structure alignment, e.g., ?align=1hho,4n7n
urlYesYesUse the url (encoded) to retrieve the 3D structure. The url requires another parameter "type", e.g., ?type=pdb&url=https%3A%2F%2Ffiles.rcsb.org%2Fview%2F1gpk.pdb
widthYesYesWidth of the structure image. It can be percentage such as '100%', or pixel values such as 400. The default is "100%".
heightYesYesHeight of the structure image. It can be percentage such as '100%', or pixel values such as 400. The default is "100%".
resizeYesYesSet "true" or "1" to resize the image when the container is resized. The default is "true".
rotateYesYesSet "right", "left", "up", or "down" to rotate the structure when it is displayed at the beginning. The default is "right".
showannoNoYesSet "true" or "1" to show annotations, such as SNPs, ClinVar, domains, binding sites. The default is "false".
showalignseqNoYesSet "true" or "1" to show the aligned sequence window. The default is "false".
showsetsNoYesSet "true" or "1" to show the defined sets. The default is "false".
show2dNoYesSet "true" or "1" to show the 2D interaction. The default is "false".
showmenuNoYesSet "false" or "0" to hide the menus and buttons at the top of the structure canvas. The default is "true".
showcommandNoYesSet "false" or "0" to hide the command window. The default is "true".
commandNoYesBesides the "Script/Log" section at the bottom of the canvas, commands can also be attached to the url parameter "command". Several commands can be concatenated with the separator ";", e.g., full.html?mmdbid=3gvu&command=select .A:38-40 or .A:42 or .A:45 or .A:61 or .A:63 or .A:77-78 or .A:82 or .A:91 or .A:107-108 or .A:110 or .A:114 or .A:162 or .A:172-173; style proteins stick; color atom; set surface Van der Waals surface; add label ATP-binding Site | size 18 | color 0000ff | background cccccc | type custom; select .STI; color green; toggle highlight.

Menus, Commands, and Methods of the advanced interfaceback to top

1. File    
MenuCommandMethod
a) Retrieve by ID
MMDB ID: load mmdb [1GPK] downloadMmdb
MMTF ID: load mmtf [1GPK] downloadMmtf
PDB ID: load pdb [1GPK] downloadPdb
mmCIF ID: load mmcif [1GPK] downloadMmcif
NCBI gi: load gi [827343227] downloadGi
PubChem CID: load cid [2244] downloadCid
b) Open File
PDB File: [no command available]
mmCIF File: [no command available]
Mol2 File: [no command available]
SDF File: [no command available]
XYZ File: [no command available]
URL (Same Host): load url [https://files.rcsb.org/view/1gpk.pdb] downloadUrl
State/Script File: [no command available] loadScript
Selection File: [no command available]
c) Open VAST Alignment
Invariant Substructure Superposed: load alignment [1HHO,4N7N] | parameters &atype=1 downloadAlignment
All Matching Molecules Superposed: load alignment [1HHO,4N7N] | parameters &atype=0 downloadAlignment
d) 3D Printing
VRML (Color, W/ Stabilizers): export vrml stabilizer file saveVrmlFile
STL (W/ Stabilizers): export stl stabilizer file saveStlFile
VRML (Color): export vrml file saveVrmlFile
STL: export stl file saveStlFile
Add All Stabilizers: stabilizer addStabilizer
Remove All Stabilizers: set stabilizer off hideStabilizer
Add One Stabilizer: add one stabilizer | [atom serial] [atom serial]
Remove One Stabilizer: remove one stabilizer | [atom serial] [atom serial]
Set Thickness: set thickness | linerad 0.6 | coilrad 1 | stickrad 0.8 | ribbonthick 0.8 | proteinwidth 2 | nucleotidewidth 1.2 | ballscale 0.6
Reset Thickness: reset thickness resetAfter3Dprint
f) Save Files
PNG Image: export canvas (URL example: https://www.ncbi.nlm.nih.gov/Structure/icn3d/full.html?mmdbid=1top&command=export%20canvas) saveFile([filename], 'png')
State File: [no command available] saveFile
All Selections: [no command available] saveFile
Residue Counts: [no command available] saveFile
Interaction List: export interactions exportInteractions
g) Share Link: [no command available] shareLink

2. Select    
MenuCommandMethod
a) Defined Sets: defined sets showSets
Select sets: select saved atoms [name1] or/and/not [name2] changeCustomAtoms
Delete selected sets: delete selected sets deleteSelectedSets
b) All: select all selectAll
c) by Distance
Display: select zone cutoff [cutoff in angstrom] pickCustomSphere
d) Inverse: select complement selectComplement
e) Side Chains: select side chains selectSideChains
f) Advancedselect [command] | name [commandname] selectByCommand

g) Select on 3D
Chain: set pk chain me.icn3d.pk = 4; me.icn3d.opts['pk'] = 'chain';
Strand/Helix (Alt): set pk strand me.icn3d.pk = 3; me.icn3d.opts['pk'] = 'strand';
Residue (Alt): set pk residue me.icn3d.pk = 2; me.icn3d.opts['pk'] = 'residue';
Atom (Alt): set pk atom me.icn3d.pk = 41; me.icn3d.opts['pk'] = 'atom';
h) Save Selection: select [command] | name [commandname] selectByCommand
i) Clear Selection: clear all selectAll

j) Highlight Color
Yellow: set highlight color yellow
Green: set highlight color green
Red: set highlight color red

k) Highlight Style
Outline: set highlight style outline me.icn3d.bHighlight = 1;
3D Objects: set highlight style 3d me.icn3d.bHighlight = 2;

2b. Selection Definition    
In the dialog Select -> Advanced, users can use simple specification to select atoms:

Specification: In the selection "$1HHO,4N7N.A,B,C:5-10,KRDE,chemicals@CA,C": Set Operation: Full commands in url or command window:

3. View    
MenuCommandMethod
a) View -> View Only Selection: show selection showSelection
b) View -> Zoom in Selection: zoom selection zoominSelection
c) View -> Center on Selection: center selection centerSelection

d) View -> Chemical Binding
Show: set chemicalbinding show me.setOption('chemicalbinding', 'show');
Hide: set chemicalbinding hide me.setOption('chemicalbinding', 'hide');

e) View -> H-Bonds to Selection
Show: hbonds [hbond threshold in angstrom] showHbonds
Hide: set hbonds off hideHbonds

f) View -> Disulfide Bonds
Show: disulfide bonds showSsbonds
Hide: set disulfide bonds off me.icn3d.opts["ssbonds"] = "no";

g) View -> Cross-Linkages
Show: cross linkage me.icn3d.bShowCrossResidueBond = true;
Hide: set cross linkage off me.icn3d.bShowCrossResidueBond = false;

h) View -> Assembly (PDB, mmCIF, or MMTF files only)
yes: set assembly on me.icn3d.bAssembly = true;
no: set assembly off me.icn3d.bAssembly = false;

i) View -> Distance
Measure: add label [label text] | x [x] y [y] z [z] | size [label size] | color [FF0000] | background [FFFFFF] addLabel
add line | x1 [x1] y1 [y1] z1 [z1] | x2 [x2] y2 [y2] z2 [z2] | color [FFFF00] | dashed [true] addLine
Hide: set lines off me.icn3d.labels['distance'] = []; me.icn3d.lines['distance'] = [];

j) View -> Label
by Picking Atoms: add label [label text] | x [x] y [y] z [z] | size [label size] | color [FF0000] | background [FFFFFF] addLabel
per Selection: add label [label text] | size [label size] | color [FF0000] | background [FFFFFF] addLabel
per Residue: add residue labels addResiudeLabels
per Chain: add chain labels addLabel
N- & C- Termini: add terminal labels addTerminiLabels
Remove: set labels off addChainLabels

k) View -> Reset:
All: reset renderFinalStep
Orientation: reset orientation resetOrientation

l) View -> Auto Rotation
Rotate Left: rotate left rotStruc
Rotate Right: rotate right rotStruc
Rotate Up: rotate up rotStruc
Rotate Down: rotate down rotStruc

m) View -> Camera
Perspective: set camera perspective me.icn3d.opts['camera'] = 'perspective';
Orthographic: set camera orthographic me.icn3d.opts['camera'] = 'orthographic';

n) View -> Fog
On: set fog on me.icn3d.opts['fog'] = 'yes';
Off: set fog off me.icn3d.opts['fog'] = 'no';

o) View -> Slab
On: set slab on me.icn3d.opts['slab'] = 'yes';
Off: set slab off me.icn3d.opts['slab'] = 'no';

p) View -> XYZ-axes
Show: set axis on me.icn3d.opts['axis'] = 'yes';
Hide: set axis off me.icn3d.opts['axis'] = 'no';
q) View -> Undo: back back
r) View -> Redo: forward forward

4. Style    
MenuCommandMethod
a) Style -> Protein
Ribbon: style proteins ribbon setStyle
Strand: style proteins strand setStyle
Cylinder and Plate: style proteins cylinder and plate setStyle
Schematic: style proteins schematic setStyle
C Alpha Trace: style proteins c alpha trace setStyle
B-factor Tube: style proteins b factor tube setStyle
Lines: style proteins lines setStyle
Stick: style proteins stick setStyle
Ball and Stick: style proteins ball and stick setStyle
Sphere: style proteins sphere setStyle
Hide: style proteins nothing setStyle

b) Style -> Side Chains
Lines: style sidec lines setStyle
Stick: style sidec stick setStyle
Ball and Stick: style sidec ball and stick setStyle
Sphere: style sidec sphere setStyle
Hide: style sidec nothing setStyle

c) Style -> Nucleotides
Nucleotide Cartoon: style nucleotides nucleotide cartoon setStyle
O3' Trace: style nucleotides o3 trace setStyle
Schematic: style nucleotides schematic setStyle
Lines: style nucleotides lines setStyle
Stick: style nucleotides stick setStyle
Ball and Stick: style nucleotides ball and stick setStyle
Sphere: style nucleotides sphere setStyle
Hide: style nucleotides nothing setStyle

d) Style -> Chemicals
Lines: style chemicals lines setStyle
Stick: style chemicals stick setStyle
Ball and Stick: style chemicals ball and stick setStyle
Schematic: style chemicals schematic setStyle
Sphere: style chemicals sphere setStyle
Hide: style chemicals nothing setStyle

e) Style -> Ions
Sphere: style ions sphere setStyle
Dot: style ions dot setStyle
Hide: style ions nothing setStyle

f) Style -> Water
Sphere: style water sphere setStyle
Dot: style water dot setStyle
Hide: style water nothing setStyle
g) Style -> Save Style: save style saveStyle
h) Style -> Apply Saved Style: apply saved style applySavedStyle

i) Style -> Surface Type
Van der Waals: set surface Van der Waals surface applySurfaceOptions
VDW with Context: set surface Van der Waals surface with context applySurfaceOptions
Molecular Surface: set surface molecular surface applySurfaceOptions
MS with Context: set surface molecular surface with context applySurfaceOptions
Solvent Accessible: set surface solvent accessible surface applySurfaceOptions
SA with Context: set surface solvent accessible surface with context applySurfaceOptions
j) Style -> Remove Surface: set surface nothing applySurfaceOptions

k) Style -> Surface Opacity
1.0: set surface opacity 1.0 applySurfaceOptions
0.9: set surface opacity 0.9 applySurfaceOptions
0.8: set surface opacity 0.8 applySurfaceOptions
0.7: set surface opacity 0.7 applySurfaceOptions
0.6: set surface opacity 0.6 applySurfaceOptions
0.5: set surface opacity 0.5 applySurfaceOptions

l) Style -> Surface Wireframe
Yes set surface wireframe on applySurfaceOptions
No set surface wireframe off applySurfaceOptions

m) Style -> Background
Transparent: set background transparent me.icn3d.opts['background'] = 'transparent'
Black: set background black me.icn3d.opts['background'] = 'black'
Grey: set background grey me.icn3d.opts['background'] = 'grey'
White: set background white me.icn3d.opts['background'] = 'white'

5. Color    
MenuCommandMethod
a)
Color -> Spectrum: color spectrum setColorByOptions
Color -> Secondary (Sheet in Green): color secondary structure setColorByOptions
Color -> Secondary (Sheet in Yellow): color secondary structure yellow setColorByOptions
Color -> Charge: color charge setColorByOptions
Color -> Hydrophobic: color hydrophobic setColorByOptions
Color -> Chain: color chain setColorByOptions
Color -> Residue: color residue setColorByOptions
Color -> Atom: color atom setColorByOptions
Color -> B-factor (Original): color b factor setColorByOptions
Color -> B-factor (Percentile): color b factor percentile setColorByOptions
Color -> Save Color: save color saveColor
Color -> Apply Saved Color:apply saved color applySavedColor

b) Color -> Unicolor
Red: color red setColorByOptions
Green: color green setColorByOptions
Blue: color blue setColorByOptions
Magenta: color magenta setColorByOptions
Yellow: color yellow setColorByOptions
Cyan: color cyan setColorByOptions
White: color white setColorByOptions
Grey: color grey setColorByOptions

c) Color -> Color Picker
Apply: color [e.g., FF0000] setColorByOptions

6. Windows    
MenuCommandMethod
a) Windows -> View Sequences & Annotations: view annotations applyCommandAnnotationsAndCddSite
b) Windows -> View Interactions view interactions set2DDiagrams

c) Windows -> View Links
Structure Summary: [no command available]
Find Similar Structures: [no command available]
Literature: [no command available]
Protein: [no command available]

7. Help    
MenuCommand
a) Help -> About iCn3D: [no command available]
b) Help -> Help DOc: [no command available]
c) Help -> Web Methods: [no command available]
d) Help -> Transform Hints: [no command available]
e) Help -> Selection Hints: [no command available]

Data Structureback to top


Display Optionsback to top


Method Documents of the core library iCn3Dback to top

Options    


bHighlight    
If its value is 1, the selected atoms will be highlighted with outlines around the structure. If its value is 2, the selected atoms will be highlighted with transparent 3D objects such as boxes, ribbons, cylinders, etc. If its value is undefined, no highlight will be shown.
bImpo    
This is a flag to turn on the rendering of spheres and cylinders using shaders instead of geometries. It's true by default if the browser supports the EXT_frag_depth extension.

bRender    
This is a flag to turn off the rendering part if a sequence of commands are executed. It's true by default.

bStopRotate    
Once clicked, this flag can be set as "true" to the automatic rotation. It's false by default.

coilWidth    
This is the coil radius for coils. It's 0.4 by default.

cylinderHelixRadius    
This is the cylinder radius for the style 'Cylinder and Plate'. It's 1.6 by default.

dAtoms    
This is a hash used to store all atoms to be displayed. The key is the atom index. Its value is set as 1.

dotSphereScale    
This is the ball scale for styles 'Ball and Stick' and 'Dot'. It's 0.3 by default.

hAtoms    
This is a hash used to store all atoms to be highlighted. The key is the atom index. Its value is set as 1.

hColor    
This defines the highlight color.

helixSheetWidth    
This is the width of protein ribbons. It's 1.3 by default.

lineRadius    
This is the line radius for stabilizers, hydrogen bonds, and distance lines. It's 0.1 by default.

matShader    
This defines the highlight color using the outline method. It can be defined using the function setOutlineColor().

nucleicAcidWidth    
This is the width of nucleotide ribbons. It's 0.8 by default.

pAtom    
"pAtom" has the value of the atom index of the picked atom.

pAtom2    
When two atoms are required to be selected (e.g., for measuring distance), "pAtom2" has the value of the atom index of the 2nd picked atom.

pk    
If its value is 1, selecting an atom will select the atom. If its value is 2, selecting an atom will select the residue containing this atom. If its value is 3, selecting an atom will select the strand or helix or coil containing this atom. If its value is 0, no selecting will work.

ribbonthickness    
This is the ribbon thickness for helix and sheet ribbons, and nucleotide ribbons. It's 0.4 by default.

sphereRadius    
This is the sphere radius for the style 'Sphere'. It's 1.5 by default.

stickRadius    
This is the stick radius for sticks. It's 0.4 by default.

traceRadius    
This is the stick radius for C alpha trace and O3' trace. It's 0.2 by default.


Methods    


addHlObjects()    
Show the highlight for the selected atoms: hAtoms.

addResiudeLabels(atoms, bSchematic)    
Add labels for all residues containing the input "atoms". The labels are one-letter residue abbreviations. If "bSchematic" is true, the labels are in circles. Otherwise, they are in round-corner rectangles.

applyDisplayOptions(options, atoms)    
Apply style and label options to a certain set of atoms.

applyOtherOptions(options)    
Apply the rest options (e.g., hydrogen bonds, center, etc).

applySsbondsOptions(options)    
Apply the disulfide bond options.

applySurfaceOptions(options)    
Apply the surface options.

applyTransformation()    
Update the rotation, translation, and zooming before rendering. Typically used before the function render().

buildAxes(radius)    
Build the xyz-axes from the center of atoms. The maximum axes length is equal to "radius" in angstrom.

calculateChemicalHbonds(protein, chemicals, threshold)    
Set up hydrogen bonds between chemical and protein/nucleotide in the same structure. "protein" and "chemicals" are hashes with atom indices as keys and 1 as values. "threshold" is the maximum distance of hydrogen bonds and has the unit of angstrom.

centerAtoms(atoms)    
Return an object {"center": center, "maxD": maxD}, where "center" is the center of a set of "atoms" with a value of THREE.Vector3(), and "maxD" is the maximum distance between any two atoms in the set.

centerSelection()    
Center on the selected atoms.

createBox(atom, defaultRadius, forceDefault, scale, color, bHighlight)    
Create a cube for "atom" with the "defaultRadius". "forceDefault" means to use the default radius. "scale" means scale on the radius. "color" means the color of the cube. "bHighlight" is an option to draw the highlight for the atom.

createCylinderCurve(atoms, atomNameArray, radius, bLines, bHighlight)    
Create small cylinders (thick lines) for "atoms", whose atom name should be in the array atomNameArray. "radius" is radius of the small cylinders. "bLine" is an option to show the cylinders as lines. "bHighlight" is an option to draw the highlight for these atoms. The highlight could be outlines with bHighlight=1 and 3D objects with bHighlight=2 as mentioned above.

createCylinderHelix(atoms, radius, bHighlight)    
Create cylinders for alpha helices and ribbons for beta strands in "atoms". "radius" is radius of the cylinders. "bHighlight" is an option to draw the highlight for these atoms. The highlight could be outlines with bHighlight=1 and 3D objects with bHighlight=2 as mentioned above.

createLabelRepresentation(labels)    
Create labels for a list of "labels", each of which has the properties 'position', 'text', 'size', 'color', and 'background'.

createLineRepresentation(atoms, bHighlight)    
Create lines for "atoms". "bHighlight" is an option to draw the highlight for these atoms. The highlight could be outlines with bHighlight=1 and 3D objects with bHighlight=2 as mentioned above.

createLines(lines)    
Create lines for a list of "lines", each of which has the properties 'position1', 'position2', 'color', and a boolean of 'dashed'.

createSphereRepresentation(atoms, radius, forceDefault, scale, bHighlight)    
Create spheres for "atoms" with the "radius". "forceDefault" means to use the default radius. "scale" means scale on the radius. "bHighlight" is an option to draw the highlight for these atoms. The highlight could be outlines with bHighlight=1 and 3D objects with bHighlight=2 as mentioned above.

createStickRepresentation(atoms, atomR, bondR, scale, bHighlight)    
Create sticks for "atoms". "bondR" is the radius of the sticks. "atomR" is the radius of the spheres in the joints. "scale" means scale on the radius. "bHighlight" is an option to draw the highlight for these atoms. The highlight could be outlines with bHighlight=1 and 3D objects with bHighlight=2 as mentioned above.

createStrand(atoms, num, div, fill, coilWidth, helixSheetWidth, doNotSmoothen, thickness, bHighlight)    
Create the style of ribbon or strand for "atoms". "num" means how many lines define the curve. "num" is 2 for ribbon and 6 for strand. "div" means how many pnts are used to smooth the curve. It's typically 5. "coilWidth" is the width of curve for coil. "helixSheetWidth" is the width of curve for helix or sheet. "doNotSmoothen" is a flag to smooth the curve or not. "thickness" is the thickness of the curve. "bHighlight" is an option to draw the highlight for these atoms. The highlight could be outlines with bHighlight=1 and 3D objects with bHighlight=2 as mentioned above.

createSurfaceRepresentation(atoms, type, wireframe, opacity)    
Create surface for "atoms". "type" can be 1 (Van der Waals surface), 2 (molecular surface), and 3 (solvent accessible surface). "wireframe" is a boolean to determine whether to show the surface as a mesh. "opacity" is a value between 0 and 1. "1" means not transparent at all. "0" means 100% transparent.

createTube(atoms, atomName, radius, bHighlight)    
Create tubes for "atoms" with certain "atomName". "radius" is the radius of the tubes. "bHighlight" is an option to draw the highlight for these atoms. The highlight could be outlines with bHighlight=1 and 3D objects with bHighlight=2 as mentioned above.

draw()    
Draw the 3D structure. It rebuilds scene, applies previous color, applies the transformation, and renders the image.
drawCartoonNucleicAcid(atoms, div, thickness, bHighlight)    
Create curves for nucleotide "atoms". "div" means how many pnts are used to smooth the curve. It's typically 5. "thickness" is the thickness of the curve. "bHighlight" is an option to draw the highlight for these atoms. The highlight could be outlines with bHighlight=1 and 3D objects with bHighlight=2 as mentioned above.

drawNucleicAcidStick(atoms, bHighlight)    
Create sticks between two nucleotide curves for nucleotide "atoms". "bHighlight" is an option to draw the highlight for these atoms. The highlight could be outlines with bHighlight=1 and 3D objects with bHighlight=2 as mentioned above.

drawSymmetryMates2()    
Draw the biological unit assembly using the matrix.

exportCanvas()    
Export the current view as a PNG file.

getAtomsWithinAtom(allAtoms, targetAtoms, distance)    
This function returns atoms within a certain "distance" (in angstrom) from the "targetAtoms". The returned atoms are stored in a hash with atom indices as keys and 1 as values. Only those atoms in "allAtoms" are considered.

getChainsFromAtoms(atomHash)    
Return the chain hash from the atom hash. The chain hash has the chainid as the key and 1 as the value.

getExtent(atomlist)    
For a list of atoms, return an array containing three coordinates: minimum x- y- z- values, maximum x- y- z- values, and average x- y- z- values.

getFirstAtomObj(atomsHash)    
Return the first atom in the atom hash, which has the atom serial number as the key.

getLastAtomObj(atomsHash)    
Return the last atom in the atom hash, which has the atom serial number as the key.

getResiduesFromAtoms(atomHash)    
Return the residue hash from the atom hash. The residue hash has the chainid as the key and 1 as the value.

hasCovalentBond(atom1, atom2)    
Determine whether atom1 and atom2 have covalent bond.

hideHbonds()    
Remove hydrogen bonds.

init()    
When users first load a structure, call this function to empty previous settings.

loadPDB(pdbData)    
This PDB parser feeds the viewer with the content of a PDB file, pdbData.

rebuildScene(options)    
This core function sets up the scene and display the structure according to the input options (shown above), which is a hash containing values for different keys.

reinitAfterLoad()    
Reset parameters for displaying the loaded structure.

removeHlObjects()    
Remove the highlight. The atom selection does not change.

removeSurfaces()    
Remove previously drawn surfaces.

render()    
Render the scene and objects into pixels.

resetOrientation()    
Set the orientation to the original one, but leave the style, color, etc alone.

residueName2Abbr(residueName)    
Convert a three-letter residue name to a one-letter residue abbreviation, e.g., 'LYS' to 'K', or ' A' to 'A' for nucleotides.

rotateDown(degree)    
Rotate the structure certain degree to the bottom, e.g., 5 degree.

rotateLeft(degree)    
Rotate the structure certain degree to the left, e.g., 5 degree.

rotateRight(degree)    
Rotate the structure certain degree to the right, e.g., 5 degree.

rotateUp(degree)    
Rotate the structure certain degree to the top, e.g., 5 degree.

saveFile(filename, type)    
Save the state file or the image file with "filename". "type" is either "text" for state file or "png" for image file.

selectStrandHelixFromAtom(atom)    
For an "atom", select all atoms in the same strand, helix, or coil.

setAtomStyleByOptions(options)    
Set atom style according to the definition in options (options.secondaryStructure, etc).

setCamera()    
Set the camera according to the size of the structure.

setColorByOptions(options, atoms)    
Set atom color according to the definition in options (options.color).

setOutlineColor(colorStr)    
Set the outline color when highlighting atoms. The available options are "yellow", "green", and "red".

setRotationCenter(coord)    
Set the center at the position with coordinated "coord".

setStyle2Atoms(atomlist)    
For a list of atoms, set the hash with style as key and atom serial as value.

setWidthHeight(width, height)    
Set the width and height of the canvas.

showPicking(atom)    
Define actions when an atom is picked. By default, the atom information ($[structure id].[chain id]:[residue number]@[atom name]) is displayed.

translateDown(percentScreenSize)    
Translate the structure certain distance to the bottom, e.g., "percentScreenSize" 1 means 1% of the screen height.

translateLeft(percentScreenSize)    
Translate the structure certain distance to the left, e.g., "percentScreenSize" 1 means 1% of the screen width.

translateRight(percentScreenSize)    
Translate the structure certain distance to the right, e.g., "percentScreenSize" 1 means 1% of the screen width.

translateUp(percentScreenSize)    
Translate the structure certain distance to the top, e.g., "percentScreenSize" 1 means 1% of the screen height.

zoomIn(normalizedFactor)    
Zoom in the structure at certain ratio, e.g., 0.1 is a reasonable value.

zoominSelection()    
Center on the selected atoms and zoom in.

zoomOut(normalizedFactor)    
Zoom out the structure at certain ratio, e.g., 0.1 is a reasonable value.

Hash Operations    

cloneHash(fromHash)    
Clone the "fromHash" and return the cloned hash.

exclHash(includeAtoms, excludeAtoms)    
Get atoms in "includeAtoms", but not in "excludeAtoms". The returned hash has atom index as key and 1 as value.

exclHash2Atoms(includeAtoms, excludeAtoms)    
Get atoms in "includeAtoms", but not in "excludeAtoms". The returned hash has atom index as key and atom object as value.

hash2Atoms(hash)    
The input "hash" has atom index as key and 1 as value. The returned hash has atom index as key and atom object as value.

intHash(atoms1, atoms2)    
Get the intersection of two hashes "atoms1" and "atoms2". The returned hash has atom index as key and 1 as value.

intHash2Atoms(atoms1, atoms2)    
Get the intersection of two hashes "atoms1" and "atoms2". The returned hash has atom index as key and atom object as value.

unionHash(atoms1, atoms2)    
Get the union of two hashes "atoms1" and "atoms2". The returned hash has atom index as key and 1 as value.

unionHash2Atoms(atoms1, atoms2)    
Get the union of two hashes "atoms1" and "atoms2". The returned hash has atom index as key and atom object as value.

Method Documents of the advanced UI library iCn3DUIback to top

Options    


b2DShown    
A flag to remember whether the 2D interaction diagram was set.

bAddCommands    
A flag to determine whether to add current step into the command history.

bAddLogs    
A flag to determine whether to add current step into the log window.

bAnnoShown    
A flag to remember whether the annotation window was set.

bSetChainsAdvancedMenu    
A flag to remember whether the menu of defined sets was set.

bNotLoadStructure    
A flag to determine whether to load the coordinates of the structure. When resetting the view, it is true so that the coordinates of the structure will not be loaded again.

cfg    
A hash containing all input parameters.

LESSHEIGHT    
The height (in px) that was left empty by the 3D viewer. The default is 20px.

LESSWIDTH    
The width (in px) that was left empty by the 3D viewer. The default is 20px.

opts    
The default display options as shown above.

pre    
A prefix for all custom html element id. It ensures all html elements have specific ids, even when multiple iCn3D viewers are shown together.

Methods    


addChainLabels(atomHash)    
Display chain name in the 3D structure display for the chains intersecting with the atoms in "atomHash".

addCustomSelection(residueAtomArray, commandname, commanddesc, command, bResidue)    
Define a custom selection based on the array of residues or atoms. The custom selection is defined by the "command" with the name "commandname" and the description "commanddesc". If "bResidue" is true, the custom selection is based on residues. Otherwise, the custom selection is based on atoms.

addLabel(text, x, y, z, size, color, background)    
Add a "text" at the position (x, y, z) with the input "size", "color", and "background".

addLine(x1, y1, z1, x2, y2, z2, color, dashed)    
Add a line between the position (x1, y1, z1) and the position (x2, y2, z2) with the input "color". The line can be dashed if "dashed" is set true.

addStabilizer()    
Add stabilizers in the model for 3D printing. This is especially important for the cartoon display such as ribbons. addTerminiLabels(atomHash)    
Display the terminal labels for the atoms in "atomHash". The termini of proteins are labeld as "N-" and "C-". The termini of nucleotides are labeled as "5'" and "3'".

allCustomEvents()    
You can add your custom events in this function if you want to add new links in the function setTools.

allEventFunctions()    
Hold all functions related to click events.

alternateStructures()    
Show structures one by one.

applyCommand(command)    
Execute a command. If the command is to load a structure, use the Method "applyCommandLoad".

applyCommandAnnotationsAndCddSite()    
The annotation window calls many Ajax calls. Thus the command "view interactions" (in Share Link or loading state file) is handled specially to wait for the Ajax calls to finish before executing the next command.

applyCommandLoad(command)    
Execute the command to load a structure. This step is different from the rest steps since it has to finish before the rest steps start.

back()    
Go back one step. Basically the commands are sequentially executed, but with one less step.

changeCustomAtoms(nameArray)    
HighlightAtoms are set up based on the selected custom names "nameArray" in the atom menu. The corresponding atoms are neither highlighted in the sequence dialog nor in the 3D structure since not all residue atom are selected.

changeSeqColor(residueArray)    
Change the residue color in the annotation window for the residues in the array "residueArray".

clearSelection()    
Clear the "Structure", "Chain", and "Custom" dropdown menu.

deleteSelectedSets()    
Delete selected sets in the menu of "Defined Sets".

downloadAlignment(align)    
Load the VAST+ structure alignment for the pair of structures "align", e.g., "align" could be "1HHO,4N7N".

downloadCid(cid)    
Ajax call was used to get the atom data from the PubChem "cid". This function was deferred so that it can be chained together with other deferred functions for sequential execution.

downloadGi(gi)    
Ajax call was used to get the atom data from the NCBI "gi". This function was deferred so that it can be chained together with other deferred functions for sequential execution. Note that only one structure corresponding to the gi will be shown. If there is no structures available for the gi, a warning message will be shown.

downloadMmcif(mmcifid)    
Ajax call was used to get the atom data from the "mmcifid". This function was deferred so that it can be chained together with other deferred functions for sequential execution.

downloadMmdb(mmdbid)    
Ajax call was used to get the atom data from the NCBI "mmdbid". This function was deferred so that it can be chained together with other deferred functions for sequential execution. If the structure is too large, a 3D dgm will show up. You can select your interested chains to see the details.

Atom "data" from MMDB file was parsed to set up parameters for the 3D viewer by calling the function loadAtomDataIn. The deferred parameter was resolved after the parsing so that other javascript code can be executed.

downloadMmtf(mmtfid)    
MMTF is a new binary data format besides the previous PDB and mmCIF formats for 3D structures. The JavaScript Methods at http://mmtf.rcsb.org/ was used to load and parse the data.

downloadPdb(pdbid)    
Ajax call was used to get the atom data from the "pdbid". This function was deferred so that it can be chained together with other deferred functions for sequential execution. A wrapper was added to support both http and https.

downloadUrl(URL, type)    
Load structures from a "URL". Due to the same domain policy of Ajax call, the URL should be in the same domain. "type" could be "pdb", "mol2", "sdf", or "xyz" for pdb file, mol2file, sdf file, and xyz file, respectively.

execCommands(steps)    
Execute a list of commands. "steps" is the total number of commands.

exportInteractions()    
Export the list of residues in some chain interacting with residues in another chain.

forward()    
Go forward one step. Basically the commands are sequentially executed, but with one more step.

getAlignSequencesAnnotations(alignChainArray, bUpdateHighlightAtoms, residueArray, bShowHighlight)    
Set up the sequence display with the aligned sequences. Either chains in "alignChainArray" or residues in "residueArray" will be highlighted. "bUpdateHighlightAtoms" is a flag to update the highlight atoms or not. "bShowHighlight" is a flag to show highlight or not.

getCommandsBeforeCrash()    
Set the commands before the browser crashed. These commands are used to restore your previous state by refreshing the crashed page. It works in Chrome, Firefox, and Internet Explorer in PC, but neither Safari nor Mac.

hideMenu(width, height)    
Hide the menu at the top and just show the canvas. "width" and "height" are the width and height of the canvas.

hideStabilizer()    
Remove all the added stabilizers.

init()    
When users load a state file, call this function to close all dialogs and reset the flags of these dialogs.


hideStabilizer()    
Remove stabilizers in the model.

isIE()    
Determine whether the current browser is Internet Explorer.

isMac()    
Determine whether it is a Mac.

isMobile()    
Determine whether it is a mobile device.

isSessionStorageSupported()    
Determine whether Session Storage is supported in your browser. Session Storage is not supported in Safari.

loadAtomDataIn(data, id, type)    
This function was used to parse atom "data" to set up parameters for the 3D viewer. "type" is mmcifid or mmdbid. "id" is the MMDB ID or mmCIF ID.

loadSdfAtomData(data)    
Atom "data" from SDF file was parsed to set up parameters for the 3D viewer. The deferred parameter was resolved after the parsing so that other javascript code can be executed.

loadMmcifData(data)    
Atom "data" from mmCIF file was parsed to set up parameters for the 3D viewer by calling the function loadAtomDataIn. The deferred parameter was resolved after the parsing so that other javascript code can be executed.

loadPdbData(data)    
Atom "data" from PDB file was parsed to set up parameters for the 3D viewer. The deferred parameter was resolved after the parsing so that other javascript code can be executed.

loadScript(commands)    
Run commands one after another. The commands can be semicolon ';' or new line '\n' separated.

modifyIcn3d()    
Hold all modification to the core iCn3D library.

modifyIcn3dshowPicking()    
Modify the function "showPicking" in the core iCn3D library.

openDialog(id, title)    
Open a dialog to input parameters. "id" is the id of the div section holding the html content. "title" is the title of the dialog. The dialog can be out of the viewing area.

outputSelection()    
Output the selected residues in the residue dialog.

pickCustomSphere(distance)    
Select a sphere around the highlight atoms with a predefined distance.

prepareFor3Dprint()    
Prepare for 3D printing by changing dashed lines to solid lines, changing the thickness of the model.

removeHl2D()    
Remove the highlight in the 2D interaction diagram.

removeHlAll()    
Remove the highlight in 3D structure, 2D interaction, 1D sequence, and the menu of defined sets.

removeHlMenus()    
Remove the selection in the menu of defined sets.

removeHlObjects()    
Remove the highlight in the 3D structure display.

removeHlSeq()    
Remove the highlight in the sequence display of the annotation window.

removeSeqChainBkgd()    
Remove the background of the highlighted chain in the sequence dialog.

removeSeqResidueBkgd()    
Remove the background of the highlighted residues in the sequence dialog.

renderFinalStep(steps)    
When reading a list of commands, apply transformation at the last step.

renderStructure()    
Update the dropdown menu and show the structure by calling the function "draw()".

resetAfter3Dprint()    
Reset the hydrogen bonds, distance lines to dashed lines. Reset the thickness to the default values.

resizeCanvas(width, height)    
Resize the canvas with the defined "width" and "height".

rotStruc(direction)    
Rotate the structure in one of the directions: "left", "right", "up", and "down".

saveCommandsToSession()    
Save the command history to session storage so that the viewer can show the previous state when refreshing the same page.

saveFile(filename, type, data)    
Five types are used: command, png, html, text, and binary. The type "command" is used to save the statefile. The type "png" is used to save the current canvas image. The type "html" is used to save html file with the "data". This can be used to save any text. The type "text" is used to save an array of text, where "data" is actually an array. The type "binary" is used to save an array of binary, where "data" is actually an array.

saveStlFile()    
Save the binary STL file for 3D monocolor printing.

saveVrmlFile()    
Save the VRML file for 3D color printing.

selectAAlignChain(alignChainid, commandname)    
Select an aligned chain with the chain id "alignChainid" in the sequence dialog and save it as a custom selection with the name "commandname".

selectAChain(chainid, commandname)    
Select a chain with the chain id "chainid" in the sequence dialog and save it as a custom selection with the name "commandname".

selectAll()    
Select all atom in the structures.

selectByCommand(command, commandname, commanddesc)    
Set a custom selection with the "command", its name "commandname" and its description "commanddesc".

selectComplement()    
Select the complement of the current selection.

selectSideChains()    
Select only the side chain atoms of the current selection.

set2DDiagrams(mmdbid)    
Generate the 2D interaction diagram for the structure "mmdbid", which could be PDB ID. The 2D interaction diagram is only available when the input is NCBI MMDB ID, i.e., the URL is something like "&mmdbid=...".

setAlignChainMenu(bInitial)    
Set the aligned chain menu. "bInitial" is a flag for the initial loading.

setAtomMenu(commandnameArray)    
Set the menu of defined sets with an array of defined names "commandnameArray".

setCustomDialogs()    
A placeholder for all custom dialogs.

setDialogs()    
Set the html for all popup dialogs.

setLogCmd(command, bSetCommand)    
Show the input command in log. If "bSetCommand" is true, the command will be saved in the state file as well.

setLogWindow()    
Set the textarea for the log output.

setMenu1()    
Set the menu "File" at the top of the viewer.

setMenu2()    
Set the menu "Select" at the top of the viewer.

setMenu3()    
Set the menu "Style" at the top of the viewer.

setMen4()    
Set the menu "Color" at the top of the viewer.

setMenu5()    
Set the menu "Surface" at the top of the viewer.

setMenu6()    
Set the menu "Other" at the top of the viewer.

setOption(id, value)    
Modify the display options, e.g., setOption('color', 'green')

setStyle(selectionType, style)    
Set the styles of predefined "protein", "nucleotides", etc.

setTools()    
Set the HTML code for the tools section. It includes several buttons, and is the second line at the top of the viewer.

setTopMenus()    
Set the HTML code for the menus shown at the top of the viewer.

shareLink()    
Generate a URL to capture the current state and open it in a new window. Basically the state file (the comand history) is concatenated in the URL to show the current state.

show3DStructure()    
The main function to show the 3D structure.

showAnnotations()    
show annotations such as SNPs, ClinVar, domains, binding sites, etc.

showCddSite(chainid, chainidBase)    
Show the annotations of CDD domains and binding sites.

showDomain(chainid, chainidBase)    
Show the annotations of 3D domains.

showHbonds(threshold)    
Show the hydrogen bonds between chemicals and proteins/nucleotides with dashed-lines."threshold" defines the distance of hydrogen bonds.

showInteraction(chainid, chainidBase)    
Show the residues interacting with the chain.

showMenu(width, height)    
Show the menu at the top and the canvas. "width" and "height" are the width and height of the canvas.

showSelection()    
Show the selection.

showSeq(chainid, chainidBase)    
Show the sequences and secondary structures.

showSets()    
Display the menu of defined sets. All chains and defined custom sets are listed in the menu. All new custom sets will be displayed in the menu.

showSnpClinvar(chainid, chainidBase)    
Show the annotations of SNPs and ClinVar.

showSsbonds()    
Show the disulfide bonds and show the side chain in the style of "stick".

showTitle()    
Show the title and PDB ID of the PDB structure at the beginning of the viewer.

toggleSelection()    
Toggle on and off the current selection.

update2DdgmContent()    
The 2D diagram only shows the currently displayed chains when users click the option "View Only Selection". This method is called to dynamically update the content of the 2D interaction diagram.

updateHl2D()    
Update the highlight of 2D interaction diagram according to the current highlighted atoms.

updateHlAll(commandnameArray, bSetMenu)    
Update the highlight of 3D structure, 2D interaction, sequences, and the menu of defined sets according to the current highlighted atoms.

updateHlMenus()    
Update the selection in the menu of defined sets according to the current highlighted atoms.

updateHlObjects()    
Update the highlight of 3D structure display according to the current highlighted atoms.

updateHlSeq()    
Update the highlight of sequences in the annotation window according to the current highlighted atoms.


Change Log:back to top

The production version icn3d-2.3.0 was release on October 18, 2018. Added set operations (union,intersection, exclusion) in "Defined Sets"; added buttons "Helix Sets" and "Sheet Sets" in the "Sequences and Annotations" window to define helix sets and sheet sets in the window "Defined Sets"; added "Save Color" and "Apply Saved Color" in the menu "Color"; added "Save Style" and "Apply Saved Style" in the menu "Style"; added "Side Chains" in the menu "Select" to select side chains; added two options for color by "Secondary" structures: "Sheets in Green" and "Sheets in Yellow"; added color by "B-factor" that is normalized with "Original" values or "Percentile" values.

The production version icn3d-2.2.5 was release on September 17, 2018. A bug in loading local PDB file was fixed.

The production version icn3d-2.2.4 was release on September 6, 2018. The location of 2D interaction dialog was optimized.

The production version icn3d-2.2.3 was release on August 30, 2018. Added an option to show N- and C-terminal labels.

The production version icn3d-2.2.2 was release on August 9, 2018. Defined sets can be combined using "or", "and", and "not".

The production version icn3d-2.2.1 was release on August 3, 2018. Mouseover on the 3D structure shows the residue or atom name. Some Ajax calls are combined into one Ajax call.

The production version icn3d-2.2.0 was release on July 30, 2018. The smoothing algorithm was switched from Catmull-Rom spline to cubic spline to make the curves more smooth. The thickness of ribbon was decreased to make the sides of the ribbons less apparent. The radio buttons in the menus was replaced by the check sign. A "Save Image" button was added in the "Toolbar".

The production version icn3d-2.1.8 was release on July 12, 2018. Checked the code with the strict mode.

The production version icn3d-2.1.7 was release on June 28, 2018. Simplified the addition of custom text as a track in the Sequences and Annotations window.

The production version icn3d-2.1.6 was release on June 21, 2018. A color picker was added to the color menu.

The production version icn3d-2.1.5 was release on June 18, 2018. 3D printing are enabled for biological assemblies.

The production version icn3d-2.1.4 was release on June 7, 2018. The retrieval of transformation matrix from mmCIF was fixed for Mac.

The production version icn3d-2.1.3 was release on May 30, 2018. "Sequences and Annotations" is now able to be highlighted even if some annotations didn't show up.

The production version icn3d-2.1.2 was release on May 23, 2018. The surface display was improved by adding light reflection. Light was added to the display of instanced biological assemblies.

The production version icn3d-2.1.1 was release on May 22, 2018. The option of color by "Spectrum" was added back.

The production version icn3d-2.1.0 was release on May 21, 2018. The instancing method is used to display a biological assembly. It significantly improved the rendering speed by sending only the geometry of its assymmetruic unit to GPU and applying transformation matrices to display the assembly.

The production version icn3d-2.0.3 was release on May 2, 2018. Removed the "Description" field when saving a set of atoms. This made "Share Link" URL shorter. Made the size of stabilizer thicker for 3D printing.

The production version icn3d-2.0.2 was release on April 30, 2018. Reset WebGLRenderer when WebGL context is lost in Internet Explore 11.

The production version icn3d-2.0.1 was release on April 23, 2018. The bug about extra 3D domains in the "Sequences & Annotations" window was fixed. The stabilizers for 3D printing were improved.

The production version icn3d-2.0.0 was release on April 17, 2018. By clicking the menu "Windows: View Sequences & Annotations", users can view all kinds of annotations: ClinVar, SNPs, CDD domains, 3D domains, binding sites, interactions, and custom tracks. Users can click the menu "View: Chemical Binding" to show the chemical binding sites. Users can also export files for 3D printing at the menu "File: 3D Printing: VRML (Color, W/ Stabilizers)".

The production version icn3d-1.4.1 was release on November 3, 2017. The version of THREE.js in the zip file was fixed.

The production version icn3d-1.4.0 was release on November 2, 2017. The rendering speed has been significantly improved by using the Imposter shaders from NGL Viewer. A bug in "Share Link" was fixed.

The production version icn3d-1.3.10 was release on October 27, 2017. The "Save File" issue in Chrome 60 and after was fixed.

The production version icn3d-1.3.9 was release on September 5, 2017. The handling of residues with insertion codes was fixed in structure alignment.

The production version icn3d-1.3.8 was release on August 7, 2017. The handling of residues with insertion codes was fixed.

The production version icn3d-1.3.7 was release on April 18, 2017. A bug in the output order of commands was fixed.

The production version icn3d-1.3.6 was release on April 10, 2017. A bug introduced in the version of icn3d-1.3.5 was fixed in the function unionHash.

The production version icn3d-1.3.5 was release on March 23, 2017. The codes were optimized to show 3D structures as soon as possible. Vast+ structure alignment was optimized as well.

The production version icn3d-1.3.4 was release on March 1, 2017. The backend of structure alignment was updated.

The production version icn3d-1.3.3 was release on November 15, 2016. Now users can save the image with "transparent" background using a single url, e.g., https://www.ncbi.nlm.nih.gov/Structure/icn3d/full.html?mmdbid=1tup&width=300&height=300&command=set%20background%20transparent;%20export%20canvas.

The production version icn3d-1.3.2 was release on October 18, 2016. The atom specification in "Advanced set selection" was modified to use "$" instead of "#" in front of structure IDs. This modification avoids to the problem of showing multiple "#" in the urls of "Share Link".

The production version icn3d-1.3.1 was release on October 4, 2016. Partial diplay of helices or beta-sheets are enabled. The side chains, if displayed, are connected to C-alphas.

The production version icn3d-1.2.3 was release on September 13, 2016. The MMTF format started to support https.

The production version icn3d-1.2.2 was release on August 18, 2016. Added a switch button to switch between all atoms and selected atoms. When the mode is "selected atoms", the switch and the text "selection" next to it are colored in orange. The menu "Style", "Color", and "Surface" are colored in orange and only apply to selected atoms.

The production version icn3d-1.2.1 was release on August 18, 2016. Some bugs were fixed.

The production version icn3d-1.2.0 was release on August 17, 2016. The dialog of 2D interactions was added to show the interactions among different chains. Both the nodes (chains) and lines (interactions) can be selected. Secondary structures will be calculated if the input PDB file has no defined secondary structure information. The previous files src/icn3d.js, src/full_ui.js, and src/simple_ui.js were separated into small files.

The production version icn3d-1.1.1 was release on July 25, 2016. Some bugs were fixed.

The production version icn3d-1.1.0 was release on July 18, 2016. The new binary MMTF file format was supported. A new "Analysis" menu was added with an option to show disulfide bonds. Users can also input data from a url, either through the UI or through a encoded url parameter "?type=pdb&url=...", e.g., https://www.ncbi.nlm.nih.gov/Structure/icn3d/full.html?type=pdb&url=https%3A%2F%2Ffiles.rcsb.org%2Fview%2F1gpk.pdb.

The production version icn3d-1.0.1 was release on May 16, 2016.

The production version icn3d-1.0.0 was release on April 28, 2016.

The beta version icn3d-0.9.6-dev was release on April 21, 2016. Enabled to export and import selection file where each custom sets of atoms are defined. Javascript files and CSS files are versioned. Developers can use the default latest version or specify the specific version in their pages.

The beta version icn3d-0.9.5-dev was release on April 4, 2016. Enabled to import Mol2, SDF, XYZ, PDB, and mmCIF files. Added "Schematic" style for chemicals. Improved the coordination between pk on 3D structure and selection on sequences.

The beta version icn3d-0.9.4-dev was release on March 14, 2016. Added "Fog" and "Slab" features.

The beta version icn3d-0.9.3-dev was release on March 9, 2016. Improved the following features: "Back" and "Forward" button, Export State, Open State.

The beta version icn3d-0.9.2-dev was release on March 4, 2016. CSS namespace was added. The file simple_ui.js was reorganized to share some codes with full_ui.js. A "Schematic" style was added to show one letter residue name in the C-alpha (for protein) or O3' (for nucleotide) position.

The beta version icn3d-0.9.1-dev was release on Feb 9, 2016. The surface generation was switched from the iview version (surface.js) to the more efficient 3Dmol version (ProteinSurface4.js and marchingcube.js).

The beta version icn3d-0.9.0-dev was release on Jan 17, 2016.