added documention for LoadImage/SaveImage and image file formats

modules/index.rst

@@ -57,6 +57,7 @@ Density Maps and Images
 
 **Overview**: :doc:`images intro <intro-02>` | :doc:`img module <img/base/img>` | :doc:`img.alg module <img/alg/alg>`
 
+**Input/Output**: :ref:`loading and saving density maps <img-io>`
 
 
 
@@ -93,7 +94,9 @@ Varia
 
 **Datasets:** :doc:`tabular data <table>`
 
-**File Formats:** :doc:`supported file formats <io/formats>`
+**File Formats:** :doc:`supported structure file formats <io/structure_formats>`
+**File Formats:** :doc:`supported sequence file formats <io/sequence_formats>`
+**File Formats:** :doc:`supported image file formats <io/image_formats>`
 
 
 Extending OpenStructure

modules/io/doc/formats.rst → modules/io/doc/image_formats.rst

-Supported File Formats
+Supported Image File Formats
 ================================================================================
 
-Structure File Formats
---------------------------------------------------------------------------------
-
-The following file formats are supported by :func:`~ost.io.LoadEntity`. 
-
-
-
-CRD - CARD format file used by CHARMM
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This trajectory file format is used by the CHARMM program suite (Molecular Modelling).
-
-*Recognized File Extensions*
-  crd
-
-PDB - Brookhaven PDB File
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Fine grained control over PDB file import is available via the 
-:func:`~ost.io.LoadPDB` function. The PDB importer supports loading gzipped PDB 
-files, which are auto-detected by the .gz file extension.
-
-*Recognized File Extensions*
-  ent, pdb, ent.gz, pdb.gz
-
-*Format Name*
-  pdb
-
-PQR
+CCP4
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  pqr
+Format used by the ccp4 software package
 
-*Format Name*
-  pqr
-  
-SDF - Structured Data File
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*Recognized File Extensions*
-  sdf
-  
-Sequence File Formats
---------------------------------------------------------------------------------
-
-FASTA
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*Recognized File Extensions*
-  fasta, fna, fas, fa, fsa
-  
-*Format Name*
-  fasta
+* Recognized file extensions: *ccp4, map*  
+* Recognized based on content: *yes*
+* File import: *yes*
+* File export: *yes*
 
-ClustalW
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  aln
-  
-*Format Name*
-  clustal
-
-Promod
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*Recognized File Extensions*
-  ali
-  
-*Format Name*
-  promod
-  
-
-Image File Formats
---------------------------------------------------------------------------------
 
 DAT
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  dat, img  
+Simple binary format for square images
+
+* Recognized file extensions: *dat, img*  
+* Recognized based on content: *no*
+* File import: *yes*
+* File export: *yes*
 
-*Format Name*
-  Simple binary format for square images
 
 DF3
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  df3
+PovRay Density file format
 
-*Format Name*
-  PovRay Density file format
+* Recognized file extensions: *df3*  
+* Recognized based on content: *no*
+* File import: *no*
+* File export: *yes*
 
 DM3
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  dm3
+Format used by Gatan Inc.'s  Digital Micrograph software
 
-*Format Name*
-  Format used by Gatan Inc.'s  Digital Micrograph software
+* Recognized file extensions: *dm3*  
+* Recognized based on content: *yes*
+* File import: *yes*
+* File export: *no*
 
 DX
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  dx  
+Format used by the OpenDX software package
 
-*Format Name*
-  Format used by the OpenDX software package
+* Recognized file extensions: *dx*  
+* Recognized based on content: *no*
+* File import: *yes*
+* File export: *yes*
 
 IPL
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  ipl  
+Ditabis Micron Image Plate Scanner Format
 
-*Format Name*
-  Ditabis Micron Image Plate Scanner Format
+* Recognized file extensions: *ipl*  
+* Recognized based on content: *yes*
+* File import: *yes*
+* File export: *yes*
 
 JPK
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  jpk
+Format used by JPK Instruments AG's software (Customized Tiff format)
 
-*Format Name*
-  Format used by JPK Instruments AG's software (Customized Tiff format)
+* Recognized file extensions: *jpk*  
+* Recognized based on content: *no (jpk files without file extension are recognized as tif)*
+* File import: *yes*
+* File export: *yes*
 
 MRC
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  map, ccp4, mrc   
+Format used by the MRC software package
 
-*Format Name*
-  Format used by the MRC software package
+* Recognized file extensions: *mrc*  
+* Recognized based on content: *yes*
+* File import: *yes*
+* File export: *yes*
 
 NanoScope
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  mod
+Format used by software from Veeco
 
-*Format Name*
-  Format used by software from Veeco
+* Recognized file extensions: *mod*  
+* Recognized based on content: *no*
+* File import: *yes*
+* File export: *yes*
 
 PNG
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  png
+Portable Network Graphic image format
 
-*Format Name*
-  Portable Network Graphic image format
+* Recognized file extensions: *png*  
+* Recognized based on content: *yes*
+* File import: *yes*
+* File export: *yes*
 
 Situs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  situs, sit
+Format used by the Situs software package
 
-*Format Name*
-  Format used by the Situs software package
+* Recognized file extensions: *situs, sit*  
+* Recognized based on content: *no*
+* File import: *yes*
+* File export: *yes*
 
-SPI
+Spider
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  spi
+Format used by the Spider software package
 
-*Format Name*
-  Format used by the Spider software package
+* Recognized file extensions: *spi*  
+* Recognized based on content: *no*
+* File import: *yes*
+* File export: *yes*
 
 TIFF
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*Recognized File Extensions*
-  tif, tiff
+Tagged Image File Format
 
-*Format Name*
-  Tagged Image File Format
+* Recognized file extensions: *tif, tiff*  
+* Recognized based on content: *yes*
+* File import: *yes*
+* File export: *yes*
 

modules/io/doc/io.rst

@@ -4,7 +4,9 @@
 .. toctree::
   :hidden:
   
-  formats
+  structure_formats
+  sequence_formats
+  image_formats
   mmcif
   profile
 
@@ -49,7 +51,7 @@ on the file extension.
     # SDF file explicitly
     ent=io.LoadEntity('file', 'sdf')
 
-  For a list of file formats supported by :func:`LoadEntity`, see :doc:`formats`.
+  For a list of file formats supported by :func:`LoadEntity`, see :doc:`structure_formats`.
   
   :raises: :exc:`~ost.io.IOUnknownFormatException` if the format string supplied 
       is not recognized or the file format can not be detected based on the 
@@ -145,7 +147,7 @@ Loading sequence or alignment files
     aln=io.LoadAlignment('algnm.aln',format="clustal")
     
   For a list of file formats supported by :func:`LoadSequence` see
-  :doc:`formats`.
+  :doc:`sequence_formats`.
   
   :raises: :exc:`~ost.io.IOUnknownFormatException` if the format string supplied 
       is not recognized or the file format can not be detected based on the 
@@ -158,13 +160,13 @@ Loading sequence or alignment files
 
   For a desription of how to use :func:`LoadSequenceList` please refer to 
   :func:`LoadSequence`. For a list of file formats supported by
-  :func:`LoadSequenceList` see :doc:`formats`.
+  :func:`LoadSequenceList` see :doc:`sequence_formats`.
 
 .. function:: LoadAlignment(filename, format='auto')
 
   For a desription of how to use :func:`LoadAlignment` please refer to 
   :func:`LoadSequence`. For a list of file formats supported by 
-  :func:`LoadAlignment` see :doc:`formats`.
+  :func:`LoadAlignment` see :doc:`sequence_formats`.
       
 Saving Sequence Data
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -185,7 +187,7 @@ Saving Sequence Data
     io.SaveAlignment(aln,'algnm.aln',format="clustal")
     
   For a list of file formats supported by :func:`SaveSequence` see
-  :doc:`formats`.
+  :doc:`sequence_formats`.
   
   :raises: :exc:`~ost.io.IOUnknownFormatException` if the format string supplied 
       is not recognized or the file format can not be detected based on the 
@@ -198,7 +200,7 @@ Saving Sequence Data
 
   For a desription of how to use :func:`SaveSequenceList` please refer to 
   :func:`SaveSequence`. For a list of file formats supported by 
-  :func:`SaveSequenceList` see :doc:`formats`.
+  :func:`SaveSequenceList` see :doc:`sequence_formats`.
 
 .. function:: SaveAlignment(aln, filename, format='auto')
 
@@ -206,7 +208,79 @@ Saving Sequence Data
   :func:`SaveSequence`.
   
   For a list of file formats supported by :func:`SaveAlignment` see 
-  :doc:`formats`.
+  :doc:`sequence_formats`.
+
+
+.. _img-io: 
+
+Density Maps
+--------------------------------------------------------------------------------
+
+Loading Density Maps
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. function:: LoadImage(filename)
+.. function:: LoadImage(filename, format)
+
+  Load density map from disk. If no format is given, the function guesses the 
+  filetype based on the extension of the file. If the extension is unknown or not present the
+  filetype will be guessed based on the content of the file if possible.
+  
+  :param filename: The filename
+  :type  filename: string
+  :param format: The file format
+
+  :raises: :exc:`~ost.io.IOUnknownFormatException` if the format supplied 
+      is not recognized or the file format can not be detected based on the 
+      file extension and content
+      
+      :exc:`~ost.io.IOException` if the import fails due to an erroneous or 
+      inexistent file
+
+  .. code-block:: python
+
+    # recognizes mrc file by file extension
+    ent=io.LoadImage('file.mrc')
+
+    # It is always possible to explicitely set the image format
+    # DAT file explicitly
+    ent=io.LoadImage('file', Dat())
+
+  For a list of file formats supported by :func:`LoadImage`, see :doc:`image_formats`.
+  
+
+
+
+Saving Density Maps
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. function:: SaveImage(image,filename)
+.. function:: SaveImage(image,filename, format)
+
+
+  Save density map to disk. If no format is set, the function guesses the 
+  filetype based on the file extension.
+  
+  :param image: The density map to be saved
+  :type  image: :class:`~ost.img.IMageHandle`
+  :param filename: The filename
+  :type  filename: string
+  :param format: The file format
+  
+  :raises: :exc:`~ost.io.IOUnknownFormatException` if the file format can not be detected based on the 
+      file extension
+
+  For a list of file formats supported by :func:`SaveImage`, see :doc:`image_formats`.
+  
+
+.. code-block:: python
+  # load density map
+  image=io.LoadImage('density_map.ccp4')
+  # save density map
+  io.SaveImage(image, 'new_map.map', CCP4())
+
+
+
 
 
 .. testsetup:: io

modules/io/doc/sequence_formats.rst

+Supported Sequence File Formats
+================================================================================
+
+FASTA
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Recognized File Extensions*
+  fasta, fna, fas, fa, fsa
+  
+*Format Name*
+  fasta
+
+ClustalW
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Recognized File Extensions*
+  aln
+  
+*Format Name*
+  clustal
+
+Promod
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Recognized File Extensions*
+  ali
+  
+*Format Name*
+  promod
+  
+

modules/io/doc/structure_formats.rst

+Supported Structure File Formats
+================================================================================
+
+The following file formats are supported by :func:`~ost.io.LoadEntity`. 
+
+
+
+CRD - CARD format file used by CHARMM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This trajectory file format is used by the CHARMM program suite (Molecular Modelling).
+
+*Recognized File Extensions*
+  crd
+
+PDB - Brookhaven PDB File
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Fine grained control over PDB file import is available via the 
+:func:`~ost.io.LoadPDB` function. The PDB importer supports loading gzipped PDB 
+files, which are auto-detected by the .gz file extension.
+
+*Recognized File Extensions*
+  ent, pdb, ent.gz, pdb.gz
+
+*Format Name*
+  pdb
+
+PQR
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Recognized File Extensions*
+  pqr
+
+*Format Name*
+  pqr
+  
+SDF - Structured Data File
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Recognized File Extensions*
+  sdf
+