Home
Hi, welcome to the KALMUS wiki page!
KALMUS is a Python package for the computational analysis of colors in films. It provides quantitative tools to study and compare the use of film color. This package serves two purposes: (1) various ways to measure, calculate and compare a film's colors and (2) various ways to visualize a film's color. We have named the software KALMUS in homage to Natalie Kalmus (1882 - 1965), a Technicolor Director who oversaw the color palettes of nearly 300 Hollywood feature films.
KALMUS utilizes the movie barcode as a visualization of the film's color. It has a modularized pipeline for the generation of barcodes using different measures of color and region of interest in each film frame. KALMUS provides both a low-level API and high-level command line and Graphic user interfaces for audience from all backgrounds to take advantage of its functionality.
- What is a Movie Barcode: KALMUS: tools for color analysis of films
- How do I install the KALMUS: KALMUS Installation Guide and KALMUS PyPI Homepage.
- How do I use the KALMUS: Notebook Tutorials for KALMUS'S API and GUI
- How do I contribute to the KALMUS: KALMUS Contribution Guidelines
- How to run KALMUS's automated test suite: Auomated Test Suite
The KALMUS API reference is now available on https://kalmus-color-toolkit.github.io/KALMUS/kalmus.html.
The kalmus package requires a python with version 3.7 or 3.8.
The package is released on PyPI (Project Homepage). After you installed the python==3.7, 3.8, you can install the kalmus using pip (recommended)
$ pip install kalmus
Alternatively, you could install the kalmus locally by first cloning this GitHub repo. Then, move to the top directory of the cloned kalmus project folder and install using the pip command
$ pip install .
In both methods, the package's dependencies will be automatically installed. You can verify if the kalmus has been installed in your environment using the pip command
$ pip show kalmus
Alternatively, in version 1.3.7 and above, you can check the version of installed kalmus using its
.__version__ attribute.
>>> import kalmus
>>> print(kalmus.__version__) # Warning: The __version__ attribute is not available in the kalmus v.1.3.6 and backward
>>> 1.3.7
KALMUS has a low-level API, high-level command line, and Graphic user interface for the audience from all backgrounds to take advantage of its functionality.
To get started on KALMUS, we encourage you to check the Jupyter notebook tutorials in the notebooks folder. We currently provide the interactive notebook tutorial for users to get started on KALMUS using its API, GUI, or CLI. Notice that the Command-line interface (CLI) is only available in KALMUS v1.3.7 or onward.
- Notebook Tutorial for Graphic User Interface
- Notebook Tutorial for Application Programming Interface
- Markdown Tutorial for Command-line interface
- Notebook Tutorial for Advanced API Usage
We encourage contributions, including bug fixes and new features, from our community users. When contributing to the Kalmus package, please first contact the project maintainers by email yc015@bucknell.edu or opening an issue. If your bug fixes or new features changing the current behavior of the package, please specify the changed behaviors and reasons for changing in the discussion with project maintainers.
We encourage inclusive and friendly discussion. Please follow our code of conduct when communicating.
We provide an automated test suite that covers the core functionality of KALMUS. Before running the automated test suite locally, make sure you have installed the latest versions of pytest, pytest-cov, and kalmus, and you have cloned the project repository on the master branch.
To run the test suite:
- Go to the top directory of cloned KALMUS project
- Use command
$ python -m pytest tests --cov=kalmus --cov-config=.coveragerc --cov-report term-missing
See Test Suite Guide under the tests folder for more details.
The authors wish to thank the Mellon Foundation, the Dalal Family Foundation, and the Bucknell University Humanities Center for their support on this project. The project is released under the open-source MIT License.
The full update log (from v1.3.0 to v1.3.12) is now available on https://kalmus-color-toolkit.github.io/KALMUS/update_log.html