************
Introduction
************

`ViewCube [+SoniCube] <https://github.com/rgbIAA/viewcube>`_ is a lightweight, standalone 
application written entirely in Python, designed for the efficient exploration and browsing 
of datacubes. Originally developed for the quick assessment of the quality and physical 
characteristics of datacubes from the CALIFA survey, and for the rapid exploration of 
high-level data products generated by the PyCASSO pipeline 
(`de Amorim et al. 2017 <https://ui.adsabs.harvard.edu/abs/2017MNRAS.471.3727D/abstract>`_), 
ViewCube’s functionality has since expanded.

The application supports datacubes from (almost) any provenance, thanks to its general 
and flexible FITS reader. This reader is agnostic to the source of the datacubes, enabling 
it to handle a wide variety of datacubes from different instruments (e.g., MUSE) and surveys 
(e.g., MaNGA, CALIFA) across various wavelength ranges (optical, radio).

Furthermore, ``ViewCube`` can visualize Raw Stacked Spectra (RSS) if a fiber position table 
is provided, either specifying the HDU extension of a FITS file or in an external ASCII file.

In addition to offering intuitive visualization and interaction with datacubes and RSS files, 
the platform features a :ref:`Sonicube<Sonicube>` interface. This unique capability enables 
auditory exploration through `sonification <https://rgb.iaa.es/que-es-la-sonificacion/>`_, 
providing a novel dimension to data analysis.


^^^^^^^^^^^^
Installation
^^^^^^^^^^^^

To get started with `ViewCube <https://github.com/rgbIAA/viewcube>`_, simply install it 
via pip using the following command:

   ``pip install viewcube``

For more information, visit the `ViewCube PyPI page <https://pypi.org/project/ViewCube/>`_.

To check the ``site-packages`` directory for a non-local Python installation, 
type the following command in the command line:

``python -m site``

Alternatively, if you want to see only the ``site-packages`` directory:

``python -c "import site; print(site.getsitepackages())"``

The installation should have placed the executable "ViewCube" file in your ``$PATH`` directory, 
making it accesible form any path.

You can check the actual location of the scrip via:

``which ViewCube``

^^^^^^^^^^^
Config file
^^^^^^^^^^^

For `ViewCube` to function, it requires a configuration file. The program searches for the file in the following order:

1. **Home Directory**:  
   A hidden file named `.viewcuberc` in the user's home directory:  

   ``$HOME/.viewcuberc``

2. **Current Directory**:  
   A non-hidden file named `viewcuberc` in the directory where `ViewCube` is executed.

If both files are found, the non-hidden file in the current directory takes precedence over the hidden file in the home directory.

"""""""""""""""""""""""""""""""
Generating a Configuration File
"""""""""""""""""""""""""""""""  

If no configuration file exists or if you wish to create a new one, you can generate a default file by running:  

``ViewCube --config-file``

- **If `$HOME/.viewcuberc` does not exist**:  
  The command will create a hidden `.viewcuberc` file in your home directory.  
- **If `$HOME/.viewcuberc` exists**:  
  The command will instead create a non-hidden `viewcuberc` file in the current directory.  

Once generated, uncomment the relevant variables in the file and set them to your desired values.


^^^^^^^^^^^^^^^^^^^^^^^^
How to cite this package
^^^^^^^^^^^^^^^^^^^^^^^^

If you use this package in your research—whether for visualization, sonification, or both—please 
cite it by including as much of the following information as possible:

Adrián García Riber, Rubén García-Benito, Francisco Serradilla. *Interactive multimodal integral 
field spectroscopy*, RAS Techniques and Instruments, Volume 3, Issue 1, January 2024, Pages 748-758
`https://doi.org/10.1093/rasti/rzae049 <https://doi.org/10.1093/rasti/rzae049>`_