**Files & Layers**
=======================
This section provides details about creating and modifying .pix files (Geomatica's working file format).
Recipes in this section also demonstrate how to import foreign file formats into .pix and 
conversely, exporting .pix files to foreign file formats.

The PCIDSK (.pix) file format is a very powerful, flexible and clean file format. As a database
file, it can store hundreds of raster channels of varying bit-depths, vector segments, bitmaps
and many other layer types in a single file. Unlike, flat files where projection, attribute information,
metadata and imagery/vectors are all stored in separate files, the pix file holds everything in 
one, easy to use file.

Create .pix (PCIDSK) file with empty channels defined
-----------------------------------------------------
    This recipe demonstrates how to create a projected .pix file with empty image channels 
    defined. Imagery can then be directly copied into these empty channels.

    .. code-block:: python

        from pci.cimpro2 import cimpro2

        new_file = r"C:\FilesLayer\empty_file.pix"
        create_channels = [4,0,1,2] #creates 4 8bit, 0 16bit signed, 1 16bit unsigned and 2 32bit real channels
        data_layout = "PIXEL" #creates data structure for file as 512x512 pixel tiles
        projection = "UTM"
        zone = [55]
        row = "G"
        datum = "D000" #D000 is WGS84. Also note that D122 is NAD83
        top_left_x = "514418.000"
        top_left_y = "5262616.000"
        bottom_right_x = "527908.000"
        bottom_right_y = "5246564.000"
        res_x = "2.0"
        res_y = "2.0"

        cimpro2(new_file, "", create_channels, data_layout, projection, zone, row, datum,
                "N", top_left_x, top_left_y, bottom_right_x, bottom_right_y, res_x, res_y,
                "", "", "", "", "", "", "", "", "", "", "", "", "", "", [], [])
        

Create .pix (PCIDSK) file with no projection defined
----------------------------------------------------
    This recipe creates a .pix file with empty channels defined by pixels and lines, but
    a coordinate system is not defined

    .. code-block:: python

        from pci.cim import cim       
        
        new_file = r"c:\new_file\empty_file.pix"
        file_size = [1024,1024] #specifies the number of pixels and lines for the output image file
        res = [15,15]
        create_channels = [7,1,2,5] #creates 7 8bit, 1 16bit signed, 2 16bit unsigned and 5 32bit real channels
        data_layout = "PIXEL" #Pixel interleaved
        
        cim(new_file, "", "", file_size, res, create_channels, data_layout)
                   

Add or delete new channel to an existing .pix file
--------------------------------------------------
    This recipe demonstrates how to quickly add a 8bit, 16bit unsigned, 16bit signed and or 32bit
    floating point channels to an existing .pix file. This can be very useful for when building custom
    models.

    .. code-block:: python

        from pci.pcimod import pcimod
        
        #Add new image channels to existing file
        file = r"c:\data\image.pix"
        channels = [4,0,3,1] #add 4 8bit, 0 16bit signed, 3 16bit unsigned and 1 32bit real channels
        
        pcimod(file, "ADD", channels)
        
        #delete image channel(s) from existing file
        file = r"c:\data\image.pix"
        channels = [1,4,6] #delete channels 1, 4 and 6
        
        pcimod(file, "DEL", channels)
       
                   
Copy image channels to an existing file with different projection 
-----------------------------------------------------------------
    This recipe demonstrates how to copy an raster channel from one file to another with different
    projections. It requires that the user reproject the source image to the same projection and bounds
    as the destination image, create an empty channel in the destination file and finally, copy the pixels.

    .. code-block:: python
        
        from pci.pcimod import pcimod
        from pci.iii import iii
        from pci.reproj2 import reproj2
        
        source_file = r"c:\data\ndvi_1.pix"
        destination_file = r"c:\data\ndvi_2.pix"
                
        #Add a new channel with correct bit-depth to destination file
        add_channel = [0,0,0,1]  
        
        pcimod(destination_file, "ADD", add_channel) #Adds a single 32 bit channel to the ndvi_2.pix file
        
        
        #reproject the source channel to the same projection and extents of destination file
        
        ''' 
        Note: for now, it is required to know the projection information of the 
        destination file. Support will be added soon to automatically retrieve this projection
        information. You can get the georeferencing information by running PROREP in terminal
        '''
        
        ndvi_channel = [5] #NDVI was calculated for this image and is stored in channel 5
        reproj_source_file = r"c:\data\ndvi_1_temp_reproj.pix"
        reproj_method = "BR" #Bounds and resolutions are unchanged, calculates pixels and lines
        resolution = [2.0, 2.0]
        map_units = "UTM 55 G D000"
        top_left_x = "514418.000"
        top_left_y = "5262616.000"
        bottom_right_x = "527908.000"
        bottom_right_y = "5246564.000"
        
        reproj2(source_file, ndvi_channel, [], "", reproj_source_file, "", "", 
                reproj_method, [], resolution, "NO", map_units, "", top_left_x, 
                top_left_y, bottom_right_x, bottom_right_y, "", "")
        
        
        #copy image channel
        input_channel = [1]
        output_channel = [6]
        
        iii(reproj_source_file, destination_file, input_channel, output_channel, [], [])
        
        
Import from foreign file to .pix or .pix link file
---------------------------------------------------
    To get the most out of Geomatics's python functions, it is often best to use the .pix format.
    This recipe demonstrates how to convert a foreign file (i.e. raw satellite file format) to
    .pix and the lightweight .pix link file.

    .. code-block:: python

        from pci.fimport import fimport
        from pci.link import link
        
        #Import foreign file to .pix file (full image copy)
        foreign_file = r"c:\kompsat-2\raw\MSC_070611154402_04650_23191328M1P17G_1G.eph" 
        pix_file = r"c:\kompsat-2\import\kompsat-2.pix"
        
        fimport(foreign_file, pix_file, [], "", "")

        
        #Import foreign file to .pix link file (link to original image)
        pix_link_file = r"c:\kompsat-2\import\kompsat-2_link.pix"
        
        link(foreign_file, pix_link_file, [])
        

Export rasters or vectors to foreign file format
-------------------------------------------------
    This recipe demonstrates how to export rasters and vectors from the .pix format to 
    a foreign file format, such as, .shp, .tif, etc.

    .. code-block:: python

        from pci.fexport import fexport 
        
        #export image raster(s) to jpeg2000 format
        pix_file = r"D:\kompsat-2.pix"
        foreign_file = r"C:\kompsat-2.jp2"
        channels = [1,2,3,4]
        format = "jp2"
        compression = "10" #result should be about 10% the size of the input image

        fexport(pix_file, foreign_file, [], channels, [], [], [], [], format, compression)
        
        
        #export vector layer
        pix_file = r"c:\data\vector.pix"
        vector_layer = [2]
        format = "shp"
                
        fexport(pix_file, foreign_file, [], [], [], vector_layer, [], [], format, "")
                
        #Note you can perform fexport to convert from a foreign file format to a different foreign file format