================
biorad1sc_reader
================

Python Package to read, parse, convert \*.1sc files generated by Bio-Rad
Quantity One software.

Documentation at: http://biorad1sc-reader.readthedocs.io/

An optional dependency: **numpy**.  If present, image operations in
biorad1sc_reader will run 4x to 5x faster.

Also installs the following command-line executables:

``bio1sc2tiff``
    converts \*.1sc files to \*.tif images. (type ``bio1sc2tiff --help``)
``bio1scmeta``
    reports all metadata contained in each \*.1sc file to a text file.
    (type ``bio1scmeta --help``)
``bio1scread``
    reports details on a \*.1sc file's internal structure.
    (type ``bio1scread --help``)

**************
Current Status
**************

* "Alpha" quality software

  * API subject to change
  * No known problems in operation.

* Reading Image Data OK
* Saving Image from file to new TIFF file OK

  * Reader.save_img_as_tiff()
  * Reader.save_img_as_tiff_sc()

* Reading all metadata OK

  * Reader.get_metadata()
  * Reader.get_metadata_compact()

* Reading certain image Metadata from Data Block 7 OK

  * Reader.get_img_summary()
  * Includes:

    * Scanner Name: <Scanner Name>
    * Number of Pixels: (<img_size_x> x <img_size_y>)
    * Image Area: (<img_size_x> mm x <img_size_y> mm)
    * Scan Memory Size: <total_img_size> Kb
    * Old file name: <old_file_name>
    * New file name: <new_file_name>
    * <File Directory>
    * New Image Acquired
    * Save As...
    * Quantity One <Quantity One Version String>

* python2 (lack of) support

  * I'm currently unwilling to support python2
  * If you'd like python2 support, it's DIY. :)

********
Examples
********

.. code:: bash

    # setup reader with input file
    import bio1sc_reader
    myreader = bio1sc_reader.Reader("my_biorad_file.1sc")
    
    # get list/dict of all metadata in 1sc file
    my_img_metadata = myreader.get_metadata()

    # get a more succinct data structure of all metadata in 1sc file
    my_img_metadata = myreader.get_metadata_compact()

    # get a quick summary of some metadata about the image in the 1sc file
    my_img_metadata = myreader.get_img_summary()

    # Different options for writing image data out as a TIFF file
    myreader.save_img_as_tif("unscaled_brightness.tif")
    myreader.save_img_as_tif("unscaled_inverted_brightness.tif", invert=True)
    myreader.save_img_as_tif_sc("scaled_brightness.tif")
    myreader.save_img_as_tif_sc("scaled_brightness_more.tif", scale=0.8)
    myreader.save_img_as_tif_sc("scaled_inverted_brightness.tif", invert=True)

**************************
File Format Documentation
**************************

* `File Specification for Bio-Rad 1sc files <http://biorad1sc-doc.readthedocs.io/>`_

************
Related Info
************
* `Bio-Rad Image Lab Software <http://www.bio-rad.com/en-cn/product/image-lab-software>`_

  * For Mac, only version 5.x supports 1sc files. (Click on the Download tab to find it.)

* `Bio-Rad Quantity One Software <http://www.bio-rad.com/en-cn/product/quantity-one-1-d-analysis-software>`_

  * Generates 1sc files from Bio-Rad instruments.

* `Bio Formats: Bio-Rad Gel 1sc file format <https://docs.openmicroscopy.org/bio-formats/5.9.0/formats/bio-rad-gel.html>`_
* `BioRadGelReader.java source <https://github.com/openmicroscopy/bioformats/blob/develop/components/formats-gpl/src/loci/formats/in/BioRadGelReader.java>`_
* `Forum post: Bio-Format 1sc to jpg batch conversion <https://www.openmicroscopy.org/community/viewtopic.php?f=13&t=2400>`_
* `reStructuredText Syntax <http://docutils.sourceforge.net/rst.html>`_
