KALMUS Update Log (v1.3.14)¶

Update Log¶

update 1.3.14¶

Add features

Now, you can rotate the 3D Bar plot in the *Colors in Hue Light 3D Bar Plot window with arrow keys. <Left> rotate counter-clockwise, <Right> rotate clockwise, <Up> from down to up, and <Down> from up to down.

Changes

Default key bindings of matplotlib plot are removed.

The light axis of the 3D Bar plot is inverted. In the default view, the bright colors are now in the foreground.

update 1.3.13¶

Add features

Color swatch. A small color display is now added to the main window under the barcode plots. When the user's mouse hovers over a pixel of the barcode, the color display will show the color of that pixel along with red, blue, green, frame, and time at that pixel. For the brightness barcode, the color display will show the brightness instead.

More configuration available for the Hue vs. Light 3D bar plot. Users may now turn on/off the shade on 3D objects, grids, and axis. The resolution of the plot (in the other words, the dimension of a 3D bar) can also be configured in the plot resolutions section. Smaller bar width on Hue/Light axis will increase the number of 3D bars in the plot (higher resolution), providing more details. Larger width will decrease the number of 3D bars and improve the performance (e.g. the refreshing speed when spinning or zooming the plot). Users can also switch to 7 pre-defined camera positions using the Camera Views.

Users can configure the plot resolution (dpi) when launching the KALMUS GUI using the -d/--dpi flag: $ kalmus-gui --dpi 160` or $ kalmus-gui -d 160. The default dpi of the GUI is 120.

Changes

When users click the browse button in the Generate barcode/Load JSON barcode window, KALMUS GUI will open the last closed folder rather than the current working directory.

Fixes

Fix the crash caused by generating and saving a barcode to an invalid JSON output file path. If you are using the save output barcode to JSON function added in v1.3.11, we recommend you update KALMUS to this new release. The KALMUS GUI may crash if you give an invalid file path to the output JSON file.

update 1.3.12¶

Add features

3D Bar plot of Hue vs. Light is now available in the Inspect Barcode window. Click the Hue vs. Light Bar Plot button to instantiate the plot.

You can press the left mouse key and drag to rotate the 3D plot or press the right mouse key to zoom in and out.

Users can select whether they want the 3D bar object to be shaded or not using the radio buttons below the plot.

This functionality is also accessible through Programming API with call to show_colors_in_hue_light_3d_bar_plot in kalmus.utils.visualization_utils.

Changes

The Calibrate button has been removed from the Check Time Point window. This button was used to fix the time-pixel relation in the barcode after rescaling/resizing the barcode. However, since version 1.3.1, KALMUS GUI automatically recalibrates the barcode when its size changes. The Calibrate button is no longer needed if you are using JSON barcodes generated from version 1.3.1 and onward.

Display button has been removed from the Check Time Point Window. KALMUS will always display the saved frames if they are available.

The Check Time Point window is always on top once generated.

Fixes

In the previous version, KALMUS will always show the longer barcode at the bottom of the window, which can be confusing. Now, a new barcode loaded from the memory/JSON object will be plotted in the exact slot selected by users.

update 1.3.11¶

Add features

A new button (Default Setting) is added in the Generate Barcode window.

Clicking this button will fill in a set of default parameters for barcode generation:

Barcode Type: Color
Frame Type: Whole_frame
Color Metric: Average
Acquisition unit: Frame
Start at: start (frame 0)
Total Frames: end (whole video)
Sample every: 2 (frames)
Save output: Checked and if output path is not given, a default output path will be filled in.
Remove letterbox: Auto
Save Frames: Checked and save a frame every 4 seconds
Rescale Frames: Unchecked

Changes

KALMUS GUI will now verify the extension of the output JSON/CSV file. If .json/.csv extension is missing, the GUI will automatically append it to the end of given path.

KALMUS GUI now gives warning to the users when saving barcode into JSON object fails.

KALMUS GUI checks if a user selects a barcode when they try to save it as a JSON object. The software will attempt to save the barcode object only if a barcode is selected.

Fixes

Fixed the scikit-image ValueError which occurs when generating Hue vs. Light plot using show_colors_in_hue_light_scatter_plot.

update 1.3.10¶

Add features

A new Hue vs. Light scatter plot is available in GUI and programming API. You can create it using the function show_colors_in_hue_light_scatter_plot from the kalmus.utils.visualization_utils:

from kalmus.utils.visualization_utils import show_colors_in_hue_light_scatter_plot
show_colors_in_hue_light_scatter_plot(colors) # colors is a numpy array of RGB colors with shape (..., 3)

Alternatively, you can visualize the Hue vs. Light scatter plot of a Barcode in KALMUS' GUI. In the main window of the GUI:

Click the Inspect Barcode button

Choose either barcode 1 or 2 (but it must be a color barcode)

In the Inspect Barcode window, click the Show Hue Light Scatter button

The Hue vs. Light scatter plot pops up

The Hue vs. Light scatter plot only shows the hue and light (brightness) dimension of the colors/color barcodes, and we set the saturation of all colors to be 1 (maximum saturation) when plotting them. To avoid artifacts created from the colorless data, we exclude all colors with saturation < 0.15 in the plot by default. This threshold can be customized in the programming API using the parameter saturation_threshold.

update 1.3.9¶

Changes

In the main plot of the KALMUS GUI, if two plotted barcodes have the same temporal dimension (elapsed time (seconds) per column of pixels), the x-ticks and y-ticks of the plot will show the pixel's temporal position (instead of the spatial position in the barcode image). See KALMUS's issue #3 for more information.

update 1.3.8¶

Changes

Default normalization for NRMSE (Normalized Root Mean Squared Error) changes to "Min max" from "Average norm". kalmus.utils.measure_utils.nrmse_similarity
SSIM is renormalized from range [-1, 1] to [0, 1] to align with the range of NRMSE for more direct comparison.
Default behavior of command-line generator kalmus-generator changed. By default, kalmus-generator now collects color till the end of film instead of only 10 frames in version 1.3.7

Fixes

Fix the issue that Barcode.fps attribute in saved JSON object is not loaded when rebuilding Barcode object. Now, the rebuilt Barcode object will have the correct fps read from JSON object file.

update 1.3.7¶

Changes

The kalmus.utils.Artist module is renamed to kalmus.utils.artist

Add features

New console script kalmus-generator that allows users to automate their barcode generation process through this command line interface. Example usage:

$ kalmus-generator -p tests/test_data/test_color_video.mp4 --frame_type Whole_frame --color_metric Average --skip 10 --step 1 --total_frames 100 --barcode_type Color

Use $ kalmus-generator -h to check the description of available arguments in details.

Update 1.3.6¶

Changes

The internal package structure is refactored.
The utility files, including artist, measure_utils, and visualization utils, are in kalmus.utils. To import artist for example, import kalmus.utils.artist.
The barcodes related class files, including Barcode and BarcodeGenerator, are in barcodes module now. To import Barcode for example, import kalmus.barcodes.Barcode.
The tkinter windows class files are further modularized.

Update 1.3.5¶

Changes

The project source codes now cloud be found on our GitHub page, https://github.com/KALMUS-Color-Toolkit/KALMUS.
If you clone the project to the local, you may start the program by running the script kalmus.py. python kalmus.py

Update 1.3.4¶

Add features

New optional parameter save frame rate in the barcode generation. Now, if users select to save the frames during the generation of the barcode, they can choose how many seconds to save one frame. The default save frame rate is saving one frame every 4 seconds.
New option and optional parameter Rescale frame in the barcode generation. Users can choose whether to rescale the input frame (reducing or enlarging the image size) during the barcode generation by a factor given by users. The rescaling the input frame to a smaller size can substantially expedite the generation process. This option is highly recommend for the input video with resolution higher than 1K standard. However, for the video with resolution lower than 1K, the time for rescaling the frame may outweigh the benefit in accelerating the barcode generation.

Changes

Now, instead of closing themselves once the process succeeded, the Generate Barcode window will give user the success message when the barcode is generated, and the window will not be closed. Meanwhile, only one generate barcode can be opened at a time, and users need to close the Generate Barcode window before exiting the program.
Load JSON window, Save JSON window, Save Image Window, and Output CSV window now also give users success message when the process is finished. Load JSON window will indicate the name (key) of the barcode loaded into the memory in its message. Save JSON window, Save Image Window, and Output CSV window will indicate where the JSON, Image, and CSV files are saved on the machine.

Fixes

The blocking issue of the Generate Barcode after users quit the KALMUS software has been fixed. Now, when users close the Generate Barcode Window and Main Window of the KALMUS GUI, all the other windows will be closed automatically and the allocated resources for their threads will be released.

update 1.3.3¶

Add features

More indicative Error Detection/Exception Handling in KALMUS graphic user interface. Now in the generate barcode, Load JSON window, Save JSON window, and Save Barcode Image window error or warning message box with issue message will pop up if any handled/unresolved exception occurred in the process.
kalmus-gui now asks users whether they are sure to quit the KALMUS when they try to close the main window by the Quit button or Close button on the Window Manager bar.

Changes

Layout of Inspect Barcode window has been redesigned. Now buttons are all on the same row, and the displayed barcode image are more compact with respect to the window.
KALMUS GUI now loads different formats of icon image under different OS environment. (.ico format for Windows and POSIX Mac, .xbm for POSIX system)
Now the histogram plots in the Main window will also be auto-rescaled after loading new barcodes into the main window.
Threaded Barcode generation. Barcode generation now won't block the mainloop process of the KALMUS GUI.

Fixes

Dependencies fixes. The required versions of dependent modules matplotlib and scikit-image now retreat to more stable releases. matplotlib == 3.2.2 and scikit-image == 0.16.2
Barcodes with less than 160 frames now can be correctly loaded and displayed in the KALMUS GUI.
Unexpected print statements in the barcode generation has been removed.

Update 1.3.1¶

Add features

Check Meta Info now also shows the input video length (time), video frame rate (FPS), generated barcode's start time, and end time in the input video. Notice that these four pieces of information are determined from the input video file and are hence immutable parameters of the video & barcode.

Changes

The default behavior of the Save Frames in the generation of the barcode is changed. The upper bound of saved frames for a barcode is 900 frames. The default sampled rate is saving one frame every 4 seconds, the sampled rate will be reduced if the resultant saved frames exceed the bound.
In the Reshape Barcode, parameters Scale Width/Height by (ratio) and Resize Width/Height to (pixels) are no longer required. If one of the parameters is not specified, rescaling/resizing will assume the barcode is unchanged in that dimension. If both dimensions (x and y) are not specified, the rescaling/resizing won't process. For reshaping, Frames per Column as the only parameter is still required, and the reshaping won't process unless the parameter is given.
In the Save JSON, the JSON file path field is no longer required. If the path is not given, the default filename of the saved barcode will be used, and the JSON file (barcode) will be saved in the current working directory. We still recommend users to specify the JSON file path to avoid potential filename conflicts.

Fixes

Unexpected print statement when Checking time at a brightness barcode is now removed.
Reshape, Resize, or Rescale a barcode will no longer break the frame-pixel (or time-pixel) relation which the function Check time at a pixel relies on. Thus, users will no need to Recalibrate the barcode to fix the time-pixel relationship after Reshape/Resize/Rescale. Calibrate now should only be used to update the time information of the barcode generated by the KALMUS in the 1.3.0 version and before. The mutability of the Barcode's start time/end time, and Frame rate are no longer needed, and the Calibrate may be removed from the KALMUS GUI in the future version.
Auto Rescale the barcode plots after loading the new barcode with different sizes (in x, y, or both dimensions) or reshaping/resizing/rescaling the currently plotted barcodes.

Update 1.3.0¶

Add features

Check time at a barcode's pixel. Users now can double clicks on a pixel in the displayed barcode to check the position, frame index, and time of the corresponding frame in the original film. All these timestamps will be showed in a separate window.
If the barcode saved the frames during the generation, users may click the Display button in the new window to check 5 frames around that time point.
The correct time relies on the assumption that each pixel in the barcode is corresponding to a sampled frame. If the barcode image has been reshaped/scaled, users can use the Calibrate button to recalibrate the frame-pixel relationship. The Frame per Second (fps) is used particularly for the downward compatibility to the barcodes generated in the previous version of KALMUS, and should not be used for the barcode generated after version 1.3.0.
Color barcode and Brightness barcode have distinguished behavior when checking the time point.

Fixes

In the Barcode Generator window, the frame acquisition parameters Start at (frames), Start at (mins:secs), Total frames, End at (mins:secs) are no longer required fields.
1. The Generator assumes the barcode starts at the beginning of the film when leaving Start at entry blank or typing Start in the entry.
2. The Generator assumes the barcode ends at the end of the film when leaving Total frames or End at entry blank or typing End in the entry.
3. The Sampled frame rate (frames or seconds) is still required.