Interface for extracting data and generating images from Jmol readable files.

JmolData is a no GUI version of Jmol useful for extracting data from files Jmol reads and for generating image files.

AUTHORS:

• Jonathan Gutow (2012-06-14): complete doctest coverage

• Jonathan Gutow (2012-03-21): initial version

class sage.interfaces.jmoldata.JmolData

Bases: SageObject

Todo

Create an animated image file (GIF) if spin is on and put data extracted from a file into a variable/string/structure to return

export_image(targetfile, datafile, datafile_cmd='script', image_type='PNG', figsize=5, **kwds)

This executes JmolData.jar to make an image file.

INPUT:

• targetfile – the full path to the file where the image should be written.

• datafile – full path to the data file Jmol can read or text of a script telling Jmol what to read or load.

• datafile_cmd – (default 'script') 'load' or 'script' should be "load" for a data file.

• image_type – (default "PNG") 'PNG' 'JPG' or 'GIF'

• figsize – number (default 5) equal to (pixels/side)/100

OUTPUT:

Image file, .png, .gif or .jpg (default .png)

Note

Examples will generate an error message if a functional Java Virtual Machine (JVM) is not installed on the machine the Sage instance is running on.

Warning

Programmers using this module should check that the JVM is available before making calls to avoid the user getting error messages. Check for the JVM using the function is_jvm_available(), which returns True if a JVM is available.

EXAMPLES:

Use Jmol to load a pdb file containing some DNA from a web data base and make an image of the DNA. If you execute this in the notebook, the image will appear in the output cell:

Sage

sage: from sage.interfaces.jmoldata import JmolData
sage: JData = JmolData()
sage: script = "load =1lcd;display DNA;moveto 0.0 { -473 -713 -518 59.94} 100.0 0.0 0.0 {21.17 26.72 27.295} 27.544636 {0.0 0.0 0.0} -25.287832 64.8414 0.0;"
sage: testfile = tmp_filename(ext="DNA.png")
sage: JData.export_image(targetfile=testfile,datafile=script,image_type="PNG")  # optional -- java internet
sage: print(os.path.exists(testfile)) # optional -- java internet
True

Python

>>> from sage.all import *
>>> from sage.interfaces.jmoldata import JmolData
>>> JData = JmolData()
>>> script = "load =1lcd;display DNA;moveto 0.0 { -473 -713 -518 59.94} 100.0 0.0 0.0 {21.17 26.72 27.295} 27.544636 {0.0 0.0 0.0} -25.287832 64.8414 0.0;"
>>> testfile = tmp_filename(ext="DNA.png")
>>> JData.export_image(targetfile=testfile,datafile=script,image_type="PNG")  # optional -- java internet
>>> print(os.path.exists(testfile)) # optional -- java internet
True

Use Jmol to save an image of a 3-D object created in Sage. This method is used internally by plot3d to generate static images. This example doesn’t have correct scaling:

Sage

sage: from sage.interfaces.jmoldata import JmolData
sage: JData = JmolData()
sage: D = dodecahedron()                                                    # needs sage.plot
sage: from tempfile import NamedTemporaryFile
sage: archive = NamedTemporaryFile(suffix=".zip")
sage: D.export_jmol(archive.name)                                           # needs sage.plot
sage: archive_native = archive.name
sage: script  = f'set defaultdirectory "f{archive_native}"\n'
sage: script += 'script SCRIPT\n'
sage: with NamedTemporaryFile(suffix=".png") as testfile:   # optional - java, needs sage.plot
....:     JData.export_image(targetfile=testfile.name,
....:                        datafile=script,
....:                        image_type="PNG")
....:     os.path.exists(testfile.name)
True
sage: archive.close()

Python

>>> from sage.all import *
>>> from sage.interfaces.jmoldata import JmolData
>>> JData = JmolData()
>>> D = dodecahedron()                                                    # needs sage.plot
>>> from tempfile import NamedTemporaryFile
>>> archive = NamedTemporaryFile(suffix=".zip")
>>> D.export_jmol(archive.name)                                           # needs sage.plot
>>> archive_native = archive.name
>>> script  = f'set defaultdirectory "f{archive_native}"\n'
>>> script += 'script SCRIPT\n'
>>> with NamedTemporaryFile(suffix=".png") as testfile:   # optional - java, needs sage.plot
...     JData.export_image(targetfile=testfile.name,
...                        datafile=script,
...                        image_type="PNG")
...     os.path.exists(testfile.name)
True
>>> archive.close()

is_jmol_available()

Returns True if jmol is available and False if not.

EXAMPLES:

Check that it returns a boolean:

Sage

sage: from sage.interfaces.jmoldata import JmolData
sage: JData = JmolData()
sage: type(JData.is_jmol_available())
<... 'bool'>

Python

>>> from sage.all import *
>>> from sage.interfaces.jmoldata import JmolData
>>> JData = JmolData()
>>> type(JData.is_jmol_available())
<... 'bool'>

is_jvm_available()

Returns True if the Java Virtual Machine is available and False if not.

EXAMPLES:

Check that it returns a boolean:

Sage

sage: from sage.interfaces.jmoldata import JmolData
sage: JData = JmolData()
sage: type(JData.is_jvm_available())
<... 'bool'>

Python

>>> from sage.all import *
>>> from sage.interfaces.jmoldata import JmolData
>>> JData = JmolData()
>>> type(JData.is_jvm_available())
<... 'bool'>

jmolpath()

Return the path to the jar file.

EXAMPLES:

Sage

sage: from sage.interfaces.jmoldata import JmolData
sage: JData = JmolData()
sage: JData.jmolpath()  # needs jmol
'.../JmolData.jar'

Python

>>> from sage.all import *
>>> from sage.interfaces.jmoldata import JmolData
>>> JData = JmolData()
>>> JData.jmolpath()  # needs jmol
'.../JmolData.jar'