v2.4.0 - Backgrounding; enables to create gray or color backgrounds; added few helper and internal functions; three new parameters: gray, rgb and cmyk backgrounds; parameters are validated for valid colors; defaults to no background (as before); updated readme and help messages

README.md

@@ -29,7 +29,7 @@ It is a dumb container of n-up binary PDF pages.
 This was on CygWin64 `@` Windows10 x64, MacOS would try `mdls` as well.
 ```
 $ pdfscale -v ../input-nup.pdf
-pdfscale v2.3.7 - Verbose Execution
+pdfscale v2.4.0 - Verbose Execution
    Single Task: Scale PDF Contents
        Dry-Run: FALSE
     Input File: ../input-nup.pdf
@@ -48,12 +48,13 @@ pdfscale v2.3.7 - Verbose Execution
  Translation X: 22.16 = 22.16 + 0.00 (offset)
  Translation Y: 15.66 = 15.66 + 0.00 (offset)
    Run Scaling: -5 %
+    Background: No background (default)
   Final Status: File created successfully
 ```
 #### Resize to A0 and Scale by 1.05 (+5%)
 ```
 $ pdfscale -v -r a0 -s 1.05 ../mixsync\ manual\ v1-2-3.pdf
-pdfscale v2.3.7 - Verbose Execution
+pdfscale v2.4.0 - Verbose Execution
    Mixed Tasks: Resize & Scale
        Dry-Run: FALSE
     Input File: ../mixsync manual v1-2-3.pdf
@@ -74,12 +75,13 @@ pdfscale v2.3.7 - Verbose Execution
  Translation X: -80.24 = -80.24 + 0.00 (offset)
  Translation Y: -56.76 = -56.76 + 0.00 (offset)
    Run Scaling: 5 %
+    Background: No background (default)
   Final Status: File created successfully
 ```
 #### Resize to A2 and disables Auto-Rotation
 ```
 $ pdfscale -v -r A2 -a none ../input.pdf
-pdfscale v2.3.7 - Verbose Execution
+pdfscale v2.4.0 - Verbose Execution
    Single Task: Resize PDF Paper
        Dry-Run: FALSE
     Input File: ../input.pdf
@@ -97,33 +99,35 @@ pdfscale v2.3.7 - Verbose Execution
 #### Resize to custom 200x300 mm, disable Flip-Detection and Scale by 0.95 (-5%)
 ```
 $ pdfscale -v -v -r 'custom mm 200 300' -f disable -s 0.95 ../mixsync\ manual\ v1-2-3.pdf
-2018-04-27:18:59:45 | pdfscale v2.3.7 - Verbose Execution
-2018-04-27:18:59:45 |    Mixed Tasks: Resize & Scale
-2018-04-27:18:59:45 |        Dry-Run: FALSE
-2018-04-27:18:59:45 |     Input File: ../mixsync manual v1-2-3.pdf
-2018-04-27:18:59:45 |    Output File: ../mixsync manual v1-2-3.CUSTOM.SCALED.pdf
-2018-04-27:18:59:45 |  Get Page Size: Adaptive Enabled
-2018-04-27:18:59:45 |         Method: Grep
-2018-04-27:18:59:45 |   Source Width: 842 postscript-points
-2018-04-27:18:59:45 |  Source Height: 595 postscript-points
-2018-04-27:18:59:45 |    Auto Rotate: PageByPage
-2018-04-27:18:59:45 |    Flip Detect: Disabled
-2018-04-27:18:59:45 |   Run Resizing: CUSTOM ( 567 x 850 ) pts
-2018-04-27:18:59:45 |      New Width: 567 postscript-points
-2018-04-27:18:59:45 |     New Height: 850 postscript-points
-2018-04-27:18:59:45 |   Scale Factor: 0.95
-2018-04-27:18:59:45 |     Vert-Align: CENTER
-2018-04-27:18:59:45 |      Hor-Align: CENTER
-2018-04-27:18:59:46 |  Translation X: 14.92 = 14.92 + 0.00 (offset)
-2018-04-27:18:59:46 |  Translation Y: 22.37 = 22.37 + 0.00 (offset)
-2018-04-27:18:59:46 |    Run Scaling: -5 %
-2018-04-27:18:59:46 |   Final Status: File created successfully
+2018-08-09:04:56:39 | pdfscale v2.4.0 - Verbose Execution
+2018-08-09:04:56:39 |    Mixed Tasks: Resize & Scale
+2018-08-09:04:56:39 |        Dry-Run: FALSE
+2018-08-09:04:56:39 |     Input File: ../mixsync manual v1-2-3.pdf
+2018-08-09:04:56:39 |    Output File: ../mixsync manual v1-2-3.CUSTOM.SCALED.pdf
+2018-08-09:04:56:39 |  Get Page Size: Adaptive Enabled
+2018-08-09:04:56:39 |         Method: Grep
+2018-08-09:04:56:39 |   Source Width: 842 postscript-points
+2018-08-09:04:56:39 |  Source Height: 595 postscript-points
+2018-08-09:04:56:40 |    Auto Rotate: PageByPage
+2018-08-09:04:56:40 |    Flip Detect: Disabled
+2018-08-09:04:56:40 |   Run Resizing: CUSTOM ( 567 x 850 ) pts
+2018-08-09:04:56:40 |      New Width: 567 postscript-points
+2018-08-09:04:56:40 |     New Height: 850 postscript-points
+2018-08-09:04:56:40 |   Scale Factor: 0.95
+2018-08-09:04:56:40 |     Vert-Align: CENTER
+2018-08-09:04:56:40 |      Hor-Align: CENTER
+2018-08-09:04:56:40 |  Translation X: 14.92 = 14.92 + 0.00 (offset)
+2018-08-09:04:56:40 |  Translation Y: 22.37 = 22.37 + 0.00 (offset)
+2018-08-09:04:56:40 |    Run Scaling: -5 %
+2018-08-09:04:56:40 |     Background: No background (default)
+2018-08-09:04:56:40 |   Final Status: File created successfully
+
 ```
 
 ## Help info
 ```
 $ pdfscale -h
-pdfscale v2.3.9
+pdfscale v2.4.0
 
 Usage: pdfscale <inFile.pdf>
        pdfscale -i <inFile.pdf>
@@ -212,6 +216,19 @@ Parameters:
  --image-resolution <dpi>
              Resolution in DPI of color and grayscale images in output
              Default: 300
+ --background-gray <percentage>
+             Creates a background with a gray color setting
+             Percentage is a floating point percentage number between 0(white) and 1(black)
+ --background-cmyk <"C M Y K">
+             Creates a background with a CMYK color setting
+             Must be quoted into a single parameter as in "0.2 0.2 0.2 0.2"
+             Each color parameter is a floating point percentage number (between 0 and 1)
+ --background-rgb <"R G B">
+             Creates a background with a RGB color setting
+             Must be quoted into a single parameter as in "100 100 200"
+             Postscript accepts both percentages or RGB numbers, but not mixed
+             Percentages are floating point numbers between 0 and 1 (1 0.5 0.2)
+             RGB numbers are integers between 0 and 255 (255 122 50)
  --dry-run, --simulate
              Just simulate execution. Will not run ghostscript
  --print-gs-call, --gs-call
@@ -283,8 +300,7 @@ Options and Parameters Parsing:
 
 Additional Notes:
  - File and folder names with spaces should be quoted or escaped
- - The scaling is centered and using a scale bigger than 1.0 may
-   result on cropping parts of the PDF
+ - Using a scale bigger than 1.0 may result on cropping parts of the PDF
  - For detailed paper types information, use: pdfscale -p
 
 Examples:
@@ -297,7 +313,6 @@ Examples:
  pdfscale -v -v -m i -s 0.7 myPdfFile.pdf
  pdfscale -r A4 myPdfFile.pdf
  pdfscale -v -v -r "custom mm 252 356" -s 0.9 -f "../input file.pdf" "../my new pdf"
-  
 ```  
   
 ## Standard Paper Tables

pdfScale.sh

@@ -5,14 +5,15 @@
 # Scale PDF to specified percentage of original size.
 #
 # Gustavo Arnosti Neves - 2016 / 07 / 10
-#        Latest Version - 2018 / 05 / 26
+#        Latest Version - 2018 / 08 / 09
 #
 # This script: https://github.com/tavinus/pdfScale
-#    Based on: http://ma.juii.net/blog/scale-page-content-of-pdf-files
+# 
+#     Related: http://ma.juii.net/blog/scale-page-content-of-pdf-files
 #         And: https://gist.github.com/MichaelJCole/86e4968dbfc13256228a
 
 
-VERSION="2.3.9"
+VERSION="2.4.0"
 
 
 ###################### EXTERNAL PROGRAMS #######################
@@ -85,6 +86,12 @@ HOR_ALIGN="CENTER"
 XTRANSOFFSET=0.0
 YTRANSOFFSET=0.0
 
+############################# Background/Bleed color creation
+BACKGROUNDTYPE="NONE"       # Should be NONE, CMYK or RGB only
+BACKGROUNDCOLOR=""          # Color parameters for CMYK(4) or RGB(3)
+BACKGROUNDCALL=""           # Actual PS call to be embedded
+BACKGROUNDLOG="No background (default)"
+
 ############################# Execution Flags
 SIMULATE=$FALSE             # Avoid execution
 PRINT_GS_CALL=$FALSE        # Print GS Call to stdout
@@ -248,6 +255,8 @@ pageScale() {
 
         local increase=$(echo "scale=0; (($SCALE - 1) * 100)/1" | "$BCBIN")
         vprint "   Run Scaling: $increase %"
+        
+        vprint "    Background: $BACKGROUNDLOG"
 
         GS_RUN_STATUS="$GS_RUN_STATUS""$(gsPageScale 2>&1)"
         GS_CALL_STRING="$GS_CALL_STRING"$'[GS SCALE CALL STARTS]\n'"$(gsPrintPageScale)"$'\n[GS SCALE CALL ENDS]\n'
@@ -269,7 +278,7 @@ gsPageScale() {
 -dSubsetFonts=true -dEmbedAllFonts=true \
 -dDEVICEWIDTHPOINTS=$PGWIDTH -dDEVICEHEIGHTPOINTS=$PGHEIGHT \
 -sOutputFile="$OUTFILEPDF" \
--c "<</BeginPage{$SCALE $SCALE scale $XTRANS $YTRANS translate}>> setpagedevice" \
+-c "<</BeginPage{$BACKGROUNDCALL$SCALE $SCALE scale $XTRANS $YTRANS translate}>> setpagedevice" \
 -f "$INFILEPDF" 
         
 }
@@ -288,8 +297,8 @@ gsPrintPageScale() {
 -dSubsetFonts=true -dEmbedAllFonts=true \
 -dDEVICEWIDTHPOINTS=$PGWIDTH -dDEVICEHEIGHTPOINTS=$PGHEIGHT \
 -sOutputFile="$OUTFILEPDF" \
--c "<</BeginPage{$SCALE $SCALE scale $XTRANS $YTRANS translate}>> setpagedevice" \
--f "$INFILEPDF" 
+-c "<</BeginPage{$BACKGROUNDCALL$SCALE $SCALE scale $XTRANS $YTRANS translate}>> setpagedevice" \
+-f "$INFILEPDF"
 _EOF_
 
         echo -ne "$_call_str"
@@ -509,6 +518,21 @@ getOptions() {
                         parseAutoRotationMode "$1"
                         shift
                         ;;
+                --background-gray)
+                        shift
+                        parseGrayBackground $1
+                        shift
+                        ;;
+                --background-rgb)
+                        shift
+                        parseRGBBackground $1
+                        shift
+                        ;;
+                --background-cmyk)
+                        shift
+                        parseCMYKBackground $1
+                        shift
+                        ;;
                 --pdf-settings)
                         shift
                         parsePDFSettings "$1"
@@ -1198,6 +1222,68 @@ parseYTransOffset() {
         exit $EXIT_INVALID_OPTION
 }
 
+# Parse Gray Background color
+parseGrayBackground() {
+        if isFloatPercentage "$1"; then
+                BACKGROUNDCOLOR="$1"
+                BACKGROUNDCALL="$BACKGROUNDCOLOR setgray clippath fill " # the space at the end is important!
+                BACKGROUNDTYPE="GRAY"
+                BACKGROUNDLOG="$GrayColor Mode > $BACKGROUNDCOLOR"
+                return $TRUE
+        fi
+        printError "Invalid Gray Background color."
+        printError "Need 1 floating point number between 0 and 1."
+        printError "Eg: --background-gray \"0.80\""
+        printError "Invalid Param => $1"
+        exit $EXIT_INVALID_OPTION
+}
+
+# Parse CMYK Background color
+parseCMYKBackground() {
+        if isFloatPercentage "$1" && isFloatPercentage "$2" && isFloatPercentage "$3" && isFloatPercentage "$4"; then
+                BACKGROUNDCOLOR="$1 $2 $3 $4"
+                BACKGROUNDCALL="$BACKGROUNDCOLOR setcmykcolor clippath fill " # the space at the end is important!
+                BACKGROUNDTYPE="CMYK"
+                BACKGROUNDLOG="$BACKGROUNDTYPE Mode > $BACKGROUNDCOLOR"
+                return $TRUE
+        fi
+        printError "Invalid CMYK Background colors."
+        printError "Need 4 floating point numbers between 0 and 1 in CMYK order."
+        printError "Eg: --background-cmyk \"C M Y K\""
+        printError "  [C] => $1"
+        printError "  [M] => $2"
+        printError "  [Y] => $3"
+        printError "  [K] => $4"
+        exit $EXIT_INVALID_OPTION
+}
+
+# Just loads the RGB Vars (without testing anything)
+loadRGBVars(){
+        BACKGROUNDCOLOR="$1 $2 $3"
+        BACKGROUNDCALL="$BACKGROUNDCOLOR setrgbcolor clippath fill " # the space at the end is important!
+        BACKGROUNDTYPE="RGB"
+        BACKGROUNDLOG="$BACKGROUNDTYPE Mode > $BACKGROUNDCOLOR"
+}
+
+# Parse RGB Background color
+parseRGBBackground() {
+        if isFloatPercentage "$1" && isFloatPercentage "$2" && isFloatPercentage "$3" ; then
+                loadRGBVars "$1" "$2" "$3"
+                return $TRUE
+        fi
+        if isRGBInteger "$1" && isRGBInteger "$2" && isRGBInteger "$3" ; then
+                loadRGBVars "$1" "$2" "$3"
+                return $TRUE
+        fi
+        printError "Invalid RGB Background colors. Need 3 parameters in  RGB order."
+        printError "Numbers can be EITHER percentages between 0 and 1 or RGB integers between 0 and 255."
+        printError "Eg: --background-rgb \"34 123 255\"" 
+        printError "  [R] => $1"
+        printError "  [G] => $2"
+        printError "  [B] => $3"
+        exit $EXIT_INVALID_OPTION
+}
+
 ################### PDF PAGE SIZE DETECTION ####################
 
 ################################################################
@@ -1362,7 +1448,7 @@ getPageSizeCatGrep() {
         mediaBox="${mediaBox##*/MediaBox}"
         mediaBox="${mediaBox##*[}"
         mediaBox="${mediaBox%%]*}"
-		#echo "mediaBox=$mediaBox"
+        #echo "mediaBox=$mediaBox"
 
         # No page size data available
         if isEmpty "$mediaBox" && isNotAdaptiveMode; then
@@ -1376,26 +1462,26 @@ getPageSizeCatGrep() {
 
         # sanity
         if [[ $mbCount -lt 4 ]] || ! isFloat "${mediaBox[2]}" || ! isFloat "${mediaBox[3]}" || isZero "${mediaBox[2]}" || isZero "${mediaBox[3]}"; then 
-				if isNotAdaptiveMode; then
-						notAdaptiveFailed $'Error when reading the page size!\nThe page size information is invalid!'
-				fi
-				return $FALSE
+                if isNotAdaptiveMode; then
+                        notAdaptiveFailed $'Error when reading the page size!\nThe page size information is invalid!'
+                fi
+                return $FALSE
         fi
 
         # we are done
         PGWIDTH=$(printf '%.0f' "${mediaBox[2]}")  # Get Round Width
         PGHEIGHT=$(printf '%.0f' "${mediaBox[3]}") # Get Round Height
 
-		#echo "PGWIDTH=$PGWIDTH // PGHEIGHT=$PGHEIGHT"
+        #echo "PGWIDTH=$PGWIDTH // PGHEIGHT=$PGHEIGHT"
         return $TRUE
 }
 
 isZero() {
-	[[ "$1" == "0" ]] && return $TRUE
-	[[ "$1" == "0.0" ]] && return $TRUE
-	[[ "$1" == "0.00" ]] && return $TRUE
-	[[ "$1" == "0.000" ]] && return $TRUE
-	return $FALSE
+    [[ "$1" == "0" ]] && return $TRUE
+    [[ "$1" == "0.0" ]] && return $TRUE
+    [[ "$1" == "0.00" ]] && return $TRUE
+    [[ "$1" == "0.000" ]] && return $TRUE
+    return $FALSE
 }
 
 # Prints error message and exits execution
@@ -1745,6 +1831,20 @@ isNotAdaptiveMode() {
 
 ########################## VALIDATORS ##########################
 
+# Returns $TRUE if we don't need to create a background
+noBackground() {
+        [[ "$BACKGROUNDTYPE" == "CMYK" ]] && return $FALSE
+        [[ "$BACKGROUNDTYPE" == "RGB" ]] && return $FALSE
+        return $TRUE
+}
+
+# Returns $TRUE if we need to create a background
+hasBackground() {
+        [[ "$BACKGROUNDTYPE" == "CMYK" ]] && return $TRUE
+        [[ "$BACKGROUNDTYPE" == "RGB" ]] && return $TRUE
+        return $FALSE
+}
+
 # Returns $TRUE if $PGWIDTH OR $PGWIDTH are empty or NOT an Integer, $FALSE otherwise
 pageSizeIsInvalid() {
         if isNotAnInteger "$PGWIDTH" || isNotAnInteger "$PGHEIGHT"; then
@@ -1781,6 +1881,12 @@ isNotAnInteger() {
         esac
 }
 
+# Returns $TRUE if $1 is an integer, $FALSE otherwise
+isRGBInteger() {
+        isAnInteger "$1" && [[ $1 -ge 0 ]] && [[ $1 -le 255 ]] && return $TRUE 
+        return $FALSE
+}
+
 # Returns $TRUE if $1 is a floating point number (or an integer), $FALSE otherwise
 isFloat() {
         [[ -n "$1" && "$1" =~ ^-?[0-9]*([.][0-9]+)?$ ]] && return $TRUE
@@ -1793,6 +1899,13 @@ isFloatBiggerThanZero() {
         return $FALSE
 }
 
+# Returns $TRUE if $1 is a floating point number between 0 and 1, $FALSE otherwise
+isFloatPercentage() {
+        [[ -n "$1" && "$1" =~ ^-?[0]*([.][0-9]+)?$ ]] && return $TRUE
+        [[ "$1" == "1" ]] && return $TRUE
+        return $FALSE
+}
+
 # Returns $TRUE if $1 is readable, $FALSE otherwise
 isReadable() {
         [[ -r "$1" ]] && return $TRUE
@@ -2000,6 +2113,19 @@ Parameters:
  --image-resolution <dpi>
              Resolution in DPI of color and grayscale images in output
              Default: 300
+ --background-gray <percentage>
+             Creates a background with a gray color setting
+             Percentage is a floating point percentage number between 0(white) and 1(black)
+ --background-cmyk <\"C M Y K\">
+             Creates a background with a CMYK color setting
+             Must be quoted into a single parameter as in \"0.2 0.2 0.2 0.2\"
+             Each color parameter is a floating point percentage number (between 0 and 1)
+ --background-rgb <\"R G B\">
+             Creates a background with a RGB color setting
+             Must be quoted into a single parameter as in \"100 100 200\"
+             Postscript accepts both percentages or RGB numbers, but not mixed
+             Percentages are floating point numbers between 0 and 1 (1 0.5 0.2)
+             RGB numbers are integers between 0 and 255 (255 122 50)
  --dry-run, --simulate
              Just simulate execution. Will not run ghostscript
  --print-gs-call, --gs-call
@@ -2062,8 +2188,7 @@ Options and Parameters Parsing:
 
 Additional Notes:
  - File and folder names with spaces should be quoted or escaped
- - The scaling is centered and using a scale bigger than 1.0 may
-   result on cropping parts of the PDF
+ - Using a scale bigger than 1.0 may result on cropping parts of the PDF
  - For detailed paper types information, use: $PDFSCALE_NAME -p
 
 Examples: