::pawt::ppmTop, Main, Index

proc ::pawt::ppm::ReadImageFile {ppmImgFile args} {

    # Read a PPM image file into a dict.
    #
    # ppmImgFile - File name of the PPM image.
    # args       - Optional format specific arguments. Currently none.
    #
    # Get the image data as a dictionary containing 2 keys: `Header` and `Data`.
    # * See [::pawt::ReadImageHeader] for the entries of the `Header` key.
    # * See [::pawt::ReadImageFile] for the entries of the `Data` key.
    #
    # Returns the image information as a dictionary.
    # If the file does not exist or no supported image format can be detected,
    # an error is thrown.
    #
    # See also: ReadImageHeader WriteImageFile

    set retVal [catch {open $ppmImgFile "r"} fp]
    if { $retVal != 0 } {
        error "Cannot open file $ppmImgFile"
    }
    fconfigure $fp -translation binary

    set imgDict [dict create]
    set headerDict [_GetImageHeader $fp [file tail $ppmImgFile]]
    _GetImageData $fp $headerDict imgDict
    dict append imgDict Header $headerDict

    close $fp
    return $imgDict
}

proc ::pawt::ppm::ReadImageHeader {ppmImgFile args} {

    # Read the header of a PPM image file.
    #
    # ppmImgFile - File name of the PPM image.
    # args       - Optional format specific arguments. Currently none.
    #
    # See [::pawt::ReadImageHeader] for the default entries of a
    # header dictionary.
    #
    # In addition to the default header dictionary entries,
    # the following keys are supported by the PPM format:
    # IsAscii - Boolean flag indicating, if the values are stored in ASCII or binary.
    #
    # Returns the header information as a dictionary.
    # If the file does not exist or the header contains invalid information,
    # an error is thrown.
    #
    # See also: ReadImageFile WriteImageFile

    set retVal [catch {open $ppmImgFile "r"} fp]
    if { $retVal != 0 } {
        error "Cannot open file $ppmImgFile"
    }
    fconfigure $fp -translation binary
    set headerDict [_GetImageHeader $fp [file tail $ppmImgFile]]
    close $fp
    return $headerDict
}

proc ::pawt::ppm::WriteImageFile {imgDict ppmImgFile args} {

    # Write the values of an image dict into a PPM image file.
    #
    # imgDict    - Image dictionary.
    # ppmImgFile - File name of the image.
    # args       - Optional format specific arguments described below.
    #
    # -datatype <string>  - Store image data as `binary`or `ascii` values.
    #                       If option is not specified, the default value is `binary`.
    # -pixeltype <string> - Store image data as `byte` or `short` values.
    #                       If option is not specified, the `PixelType` value of the
    #                       dictionary is used.
    #
    # * PPM files are always stored in `TopDown` scan order.
    # * Binary PPM files are always stored in `Motorola` byte order.
    #
    # See [::pawt::WriteImageFile] for general informations regarding writing images.
    #
    # Returns no value. If invalid options are specified or the file could not
    # be written, an error is thrown.
    #
    # See also: ReadImageFile ReadImageHeader

    set opts [dict create  -datatype  "binary"  -pixeltype ""  ]

    foreach { key value } $args {
        if { [dict exists $opts $key] } {
            if { $value eq "" } {
                error "WriteImageFile: No value specified for key \"$key\"."
            }
            dict set opts $key $value
        } else {
            error "WriteImageFile: Unknown option \"$key\" specified."
        }
    }

    set isAscii false
    if { [dict get $opts "-datatype"] eq "ascii" } {
        set isAscii true
    }

    set retVal [catch {open $ppmImgFile "w"} fp]
    if { $retVal != 0 } {
        error "Cannot open output file $ppmImgFile"
    }
    fconfigure $fp -translation binary

    _PutImageHeader $fp [dict get $imgDict Header] $isAscii
    _PutImageData   $fp imgDict $isAscii
    close $fp
}