--- /dev/null
+# createoverlay\r
+Command-line utility for creating viewfinder overlays with custom aspect ratio framelines and grid lines, which can then be converted into Nikon NEF raw files and used with Nikon's multiple exposure overlay feature for shooting with Nikon Z cameras - see the [Using overlays with Nikon's multiple exposure feature](#using-overlays-with-nikon-multiple-exposure-feature) for details.\r
+\r
+## Requirements\r
+createoverlay is part of [imgn2ef](img2nef.md) and runs on Windows, Mac, and Linux. It requires Python 3.10 or later, which can be [downloaded here](https://www.python.org/downloads/). The following additional Python packages are required:\r
+\r
+ pip install pillow\r
+\r
+createoverlay is part of the img2nef project, which is required to convert the generated overlay into a Nikon NEF raw.\r
+\r
+## Installation\r
+Download img2nef by [clicking here](https://github.com/horshack-dpreview/img2nef/archive/refs/heads/main.zip) and unzip into a directory of your choice, or if you have git:\r
+\r
+ `git clone https://github.com/horshack-dpreview/img2nef.git`\r
+\r
+## Running\r
+Depending on your platform, createoverlay can be started in one of the following ways:\r
+* python createoverlay.py\r
+* python3 createoverlay.py\r
+* createoverlay.py\r
+\r
+## Quick Start\r
+createoverlay has many options but only two parameters are typically required:\r
+* Nikon Camera Model\r
+* At least one frameline or gridline specification\r
+\r
+### Examples:\r
+`python createoverlay.py Z6III --frameline 16:9`\r
+Creates a 16:9 frameline with default line and fill characteristics for a Nikon Z6 III as a PNG file, then converts the PNG to a NIkon Z6 III NEF raw. The resulting PNG is opened in your system's default image viewer.\r
+\r
+\r
+\r
+`python createoverlay.py Z6III --gridline 4x4`\r
+Creates a 4x4 gridline with default line and fill characteristics for a Nikon Z6 III.\r
+\r
+\r
+`python createoverlay.py Z6III --frameline 16:9 --frameline 1:1,dashedline=50-50,linecolor=#ff0000`\r
+Creates a 16:9 solid-line white frameline and a 1:1 dashed red frameline.\r
+\r
+\r
+## Automatic output filename\r
+When no output filename is specified createoverlay will automatically generate one, which by default is the concatenation of the camera model and each of the frameline and gridlines you specified, stored in the current working directory. For the first example this will be `Overlay_Z6III_Frame-16x9.PNG` and the second `Overlay_Z6III_Grid-4x4.PNG`.\r
+\r
+## More output options\r
+`<output filename>`\r
+You can explicitly specify the output filename by providing an additional argument. It can include an optional path as well. If any part of the path or filename has spaces you must enclose the entire text in double quotes. Example:\r
+\r
+`createoverlay Z6III --frameline 16:9 "c:\My Documents\MyGrid.PNG"`\r
+\r
+### `--outputdir <path>`\r
+Directory to store the generated overlay into. If this is specified without an `<output filename>` then createoverlay will generate the output filename automatically and store it in the `--outputdir` path.\r
+\r
+### `--ifexists ADDSUFFIX | OVERWRITE | EXIT`\r
+\r
+Action to take if the output file already exists. `ADDSUFFIX` iteratively adds a numerical suffix to the filename until a unique name is generated (ex: "file-1.nef", "file-2.nef", etc...). `OVERWRITE` overwrites the existing file. `EXIT` terminates the app without writing the output. Default is `ADDSUFFIX`.\r
+\r
+## All options\r
+\r
+### `--frameline aspectratio=columns:rows, linewidth=#pixels, dashedline=dashlen-gaplen, linecolor=#RRGGBB, fillcolor=#RRGGBB, labelpos=vert-horz`\r
+\r
+Each frameline parameter is separated with commas, with no spaces allowed - a space will be interpreted as the next command-line option.\r
+\r
+`aspectratio` is the relationship of width vs height for the frameline. This parameter is required. All other parameters are optional.\r
+\r
+`linewidth` is the width of the line drawn for the frameline, in pixels. Default is 32.\r
+\r
+`dashedline` sets a repeating dashed pattern for the line. The first value is the length of the drawn segment, the second is the length of the gap between segments. Specify 'none' or no value for a solid line. Default is none (solid line).\r
+\r
+`linecolor` sets the color of the line, specified in three 2-digit RGB hex values. Default is #000000 (black).\r
+\r
+`fillcolor` sets the interior color of the aspect ratio box, specified in three 2-digit RGB hex values. Default is none (no fill), which means the global `--backgroundcolor` setting will determine the interior color of the aspect ratio area. You can experiment with different fill colors/brightnesses vs the various compositing modes supporting by Nikon's multiple exposure feature to visually isolate the aspect ratio area to your preference.\r
+\r
+`labelpos` sets the label position and visibility of the aspect ratio label. Values for `vertpos` are `Top, Center, Bottom` and for `horzpos` are `Left, Center, Right`. For no label specify `none` or no value. Default is Bottom-Left.\r
+\r
+The `aspectratio` parameter is required - all others are optional. Any parameter not specified will use the default for that setting, which can be set separately via that option name outside of a `--frameline`. For example:\r
+\r
+`--frameline 4:3 --frameline 16:9,linecolor=#ff0000 --linecolor=#0000ff`\r
+Creates a 4:3 frameline using all default values; the default `linecolor` was specified as blue, so the 4:3 frameline will be blue. A 16:9 frameline is also created with a line color of red since that color was specified for that frameline. \r
+\r
+You can optionally leave out the parameter name and just provide the values instead. Use an empty field to skip a value. For example:\r
+\r
+`--frameline 1:1,16,5-10,,,center-left`\r
+Creates a 1:1 frameline with a line width of 16 pixels, dash pattern of 5 pixels with 10 pixel gaps, default line and fill colors (empty fields), and an aspect ratio label position vertically centered on the left side of the frame.\r
+\r
+### `--gridline griddimensions=columns x rows, aspectratio=columns:rows, linewidth=#pixels,dashedline=dashlen-gaplen, linecolor=#RRGGBB`\r
+\r
+Each gridline parameter is separated with commas, with no spaces allowed - a space will be interpreted as the next command-line option.\r
+\r
+Multiple `--gridline` options can be specified, although note they'll typically overlap each other visually.\r
+\r
+`griddimensions`sets the dimensions of the grid, as number of columns and rows. One of the axis can be zero if desired, creating only rows or columns.\r
+\r
+Each column/row is demarcated by vertical and horizontal lines, so the number of lines will be the column/row values minus 1. For example, here is a `--gridline 4x4`\r
+\r
+Note there are three horizontal and vertical lines, creating 4 columns and 4 rows.\r
+\r
+`aspectratio` optionally confines the grid to an aspect ratio. The full 3:2 sensor area is used for the grid when `aspectratio` is not specified.\r
+\r
+`linewidth` is the width of the line drawn for the frameline, in pixels. Default is 32.\r
+\r
+`dashedline` sets a repeating dashed pattern for the line. The first value is the length of the drawn segment, the second is the length of the gap between segments. Specify 'none' or no value for a solid line. Default is none (solid line).\r
+\r
+`linecolor` sets the color of the line, specified in three 2-digit RGB hex values. Default is #000000 (black).\r
+\r
+You can optionally leave out the parameter name and just provide the values instead. Use an empty field to skip a value. For example:\r
+\r
+`--gridline 4x4,,16,,#ff0000`\r
+Creates a 4:4 grid with default aspect ratio (3:2), a line width of 16 pixels, no dash pattern (solid line by default), and line color of red.\r
+\r
+### `--linewidth #pixels`\r
+Sets the default line width, used when not explicitly specified in a `--frameline` and `--gridline` specification. Default is 32.\r
+\r
+### `-linecolor #RRGGBB`\r
+Sets the default line color, used when not explicitly specified in a `--frameline` and `--gridline` specification. Default is #000000 (black).\r
+\r
+### `-dashedline dashlen-gaplen`\r
+Sets the default line type, used when not explicitly specified in a `--frameline` and `--gridline` specification. The first value is the length of the drawn segment, the second is the length of the gap between segments. Specify 'none' or no value for a solid line. Default is none (solid line).\r
+\r
+### `--labelpos vertpos-horzpos`\r
+Sets the default label position and visibility, used when not explicitly specified in a `--frameline` Values for `vertpos` are `Top, Center, Bottom` and for `horzpos` are `Left, Center, Right`. For no label specify `none` Default is bottom-left.\r
+\r
+### `--backgroundcolor #RRGGBB`\r
+Sets the "global" background color of the entire overlay. This color will be visible for any portion of the frame not covered by a frameline box as well as any frameline box with no fill color. Default is #000000 (black).\r
+\r
+### `--fontsizepct font-size-pct`\r
+Sets the size of the aspect ratio label as a percentage of the raw picture height. Default is 5%. Note the font size cannot be set on a per-frameline basis (ie, applies to all framelines that enable a label).\r
+\r
+### `--dimensions raw columns x rows, jpg columns x rows`\r
+Normally the raw and jpg dimensions are established by the camera model specified. You can override those dimensions with this option, or provide them when no model is specified. Example:\r
+\r
+`--dimensions 6048x4032,6000x4000`\r
+\r
+### `--imagetype extension`\r
+Determines the image format of the generated overlay, specified via the file extension of the format. Default is PNG.\r
+\r
+### `--openinviewer yes | no`\r
+Open the generated overlay in your system's default image viewer. Default is yes. If a yes/no value is not specified then the option is interpreted as `yes`.\r
+\r
+### `--generatenef yes | no`\r
+Use img2nef to generate a Nikon raw NEF from the overlay created. The NEF location and filename will be the same as the generated overlay image but with a .NEF extension. If set to no then only the overlay image will be created and no NEF. Default is yes. If a yes/no value is not specified then the option is interpreted as `yes`.\r
+\r
+### `--list-cameras`\r
+Show list of predefined camera models and their raw+jpg resolutions. Same as running `python cameras.py`.\r
+\r
+### `--verbosity SILENT | WARNING | INFO | VERBOSE | DEBUG`\r
+Verbosity of output during execution. Default is `INFO`. When `SILENT`, only error messages are displayed.\r
+\r
+## Specifying options in separate file, including default options\r
+In addition to supplying options on the command line, you can also place additional options in a text file and supply its filename by placing a `!` before it. For example:\r
+\r
+`createoverlay !myoptions.txt --generatenef no`\r
+\r
+In the text file each option must be on a separate line, and any values for the option must be connected via an equal sign instead of space, otherwise the value will be interpreted as a different option. Example `myoptions.txt`\r
+```\r
+--openinviewer=no\r
+--fontsizepct=15% \r
+```\r
+Besides your own option text files, createoverlay will always load any option text file named `.createoverlay-defaultoptions` in its directory. The options in this file will be loaded and applied before any of the options you specify, allowing you to create your own application defaults.\r
+\r
+## Using Overlays with Nikon Multiple Exposure Feature\r
+Once you've created your viewfinder overlay (including its conversion to raw) you can use it with Nikon's in-camera Multiple Exposure feature. This feature allows you to combine multiple exposures into a single composite jpg, including optionally saving each individual raw taken in the process. It also provides an option to supply an existing raw file as the first image in the composite, and includes the ability to view that raw file as an overlay while shooting. With this ability you can use the overlays created by `createoverlay` as framing guides during shoot.\r
+\r
+### Copying overlay raws to the media card\r
+Normally the camera only allows you to specify raw images taken by the camera itself, since the camera's feature wasn't designed with the possibility that users could supply their own raws. Specifically, the camera will only let you choose a raw image that it believes it created and put on the card. The camera knows which files it has shot via the `NC_FILLST.DAT` file it manages in each image directory. To get the camera to "see" our overlay files we must replace an existing raw image with the overlay file, using that existing raw's filename. That way the camera will believe it shot the overlay and allow you to select it. This means you'll need to take a throwaway raw photo so that you'll have an image to replace (ie, one you don't mind deleting).\r
+\r
+Here's the procedure:\r
+\r
+ 1. Take a throw-away raw photo with the camera, or multiple photos if you're planning to use multiple overlays.\r
+ 2. Mount the media card in a card reader on your computer and navigate to the DCIM directory containing the raw images you just shot.\r
+ 3. Copy the overlay raws you created from the computer to the DCIM directory on the card.\r
+ 4. Identify the file on the card associated with the "throwaway" photo you took with the camera. For example, `DSC_0169.NEF`. Copy that filename to the clipboard if possible, then delete the file.\r
+ 5. Select the overlay raw on the card and rename it to whatever the throwaway's filename was. For example, renaming `Overlay_Z6III_Frame-16x9.NEF` to `DSC_0169.NEF`. The easiest way to rename the overlay is using your Operating System's context menu on the throwaway file and choosing "rename", then pasting the filename you copied from step 4. Be careful the renamed file has only one extension (.NEF), as some renaming options only select the root filename and so pasting the full filename might result in two .NEF extensions.\r
+ 6. Repeat steps 4 and 5 for each throwaway file that you're replacing with an overlay.\r
+ 7. Safely dismount the media card and insert it back into the camera.\r
+\r
+### Configuring the Multiple Exposure feature\r
+\r
+1. Go to the PHOTO SHOOTING MENU and enter the Muliple exposure option.\r
+\r
+\r
+\r
+3. Set the multiple exposure options to:\r
+* Multiple exposure mode to "On (series)",\r
+* Number of shots to 2\r
+* Overlay mode to Ligthen (you can experiment with different modes to preference)\r
+* Save individual pictures (RAW) to "ON"\r
+* Overlay shooting to "ON"\r
+\r
+\r
+\r
+4. Use `Select first exposure (RAW)` and navigate to the overlay raw you'd like to use.\r
+\r
+\r
+\r
+5. Half-press the shutter to return to shooting mode. \r
+\r
+### Shooting with the Multiple Exposure feature\r
+\r
+The camera previews the multiple exposure by compositing the overlay raw you selected over the active scene.\r
+\r
+\r
+When you take a picture the camera stores two images on the card - a composite jpg that combines content from the overlay raw with the scene content, using whichever composting mode you selected, and a raw imge, which has only the scene content that is no different than if it were shot outside of the multiple exposure mode.\r
+\r
+Note that the composite jpg will not look the same as the previewed composite that was presented while shooting - apparently the camera applies a different compositing algorithm for its Live View preview than it does for the resulting composite photo.\r
+\r
+After shooting the multiple exposure photo the camera unfortunately resets the configuration you set for the first raw, which means if you start another multiple exposure sequence it will not automatically use the overlay raw you configured. You'll either need to dive back into the multiple exposure menu to configure the overlay again or preferably, use the following procedure to create a shortcut which does this.\r
+\r
+Note: You'll probably want to turn off the camera's [Image Frame option](https://onlinemanual.nikonimglib.com/z6III/en/csmd_image_frame_251.html) - this option draws a white border around the frame that can visually clashes with the overlay.\r
+\r
+### Configuring and using shortcut for setting the overlay raw\r
+\r
+After every multiple exposure photo the camera resets the configured overlay raw, requiring you to set it again to use for the next photo. I've developed the following shortcut that helps workaround this limitation, or at least reduce it to a set of fixed camera control inputs that you can memorize and use without having to look at the menu system.\r
+\r
+1. Add Multiple exposure to the top of your MY MENU by going to `MY MENU` -> `Add items` -> `PHOTO SHOOTING MENU` -> `Multiple exposure` and choosing the first position in your MY MENU. You can also use `Rank items` to reposition `Multiple exposure` to the top of the menu.\r
+\r
+\r
+2. Configure a function control to `Access top item in MY MENU` by going to `CUSTOM SETTINGS MENU` -> `Controls` -> `Custom controls (shooting)` and selecting a control to assign\r
+\r
+\r
+\r
+Select the desired control and assign it to `Access top item in MY MENU`.\r
+\r
+\r
+\r
+3. Ideally you want your overlay raw to be the first file on the media card. This is because the camera always defaults to the most recent raw when you're prompted to `Select first exposure (RAW)`. By having the overlay as the oldest raw, you can always select it via a single right-button click on the multi-control dial because that will wrap the selection around from the newest to oldest image.\r
+\r
+The easiest way to make the overlay the oldest raw on the camera is to format the card in-camera, take a throwaway picture with the camera (raw), then replace the throwaway raw with your overlay raw, ie rename the overlay raw to the throwaway raw.\r
+\r
+#### Using the shortcut\r
+With all that setup out of the way, the procedure to re-select your overlay raw for every photo is:\r
+\r
+1. Press the Fn button you assigned to `Access top item in MY MENU` to open the Multiple exposure menu with the last sub-menu item used selected, which will be `Select first exposure (RAW)`.\r
+2. Press the right-button on the rear multi-selector to enter `Select first exposure (RAW)` image selection.\r
+3. Press the right-button on the rear multi-selector to moves selection from newest to oldest raw.\r
+4. Press the center button on the rear multi-selector to accept the oldest raw selection.\r
+5. Half-press the shutter to re-enter shooting mode.\r
+\r
+\r
+\r
+Obviously these are more clicks than ideal but the sequence is easy commit to muscle memory and perform without having to actually look at the menus while you perform them.
\ No newline at end of file
git.99rst.org / horshack-dpreview-img2nef.git / commitdiff