Build Instructions

🇯🇵 日本語版 / Available in Japanese

日本語で読みたい方はこちらのページをご覧ください。
Please see the Japanese version for reading in Japanese.

Caution

This page is intended for developers.

This section explains how to build the application.

The application is built using PyInstaller.

A pre-generated spec file is provided and should be used for building the application.
Please note that this process can take some time (approximately 10 minutes).

pyinstaller build.spec

For more details on PyInstaller usage, please refer to the official documentation.

Notes

Currently, builds have only been tested on Windows.
We plan to support other operating systems in the future.
The provided spec file runs without errors, but there is still room for refactoring and optimization. Improvements will be made in future updates.
For details about spec files, see Using Spec FIles - PyInstaller.

Removing Previous Builds

Before running PyInstaller, it is recommended to remove any existing build artifacts:

Remove-Item -Recurse -Force build, dist

After Building

If the build completes successfully, the following directory structure will be generated at the project root:

project/
├─ build/
└─ dist/
   └─ LeafShapeTool/
      ├─ LeafShapeTool.exe
      └─ _internal/
         └─ (library files)

The main executable is located at:

dist/LeafShapeTool/LeafShapeTool.exe

You can launch the application either by double-clicking the file or from the command line:

cd dist/LeafShapeTool/
LeafShapeTool.exe

Double-Click vs. Command Line Launch

When launched by double-clicking, a console window appears for log and error output. However, the console closes automatically after execution ends, which may make it difficult to check messages. In such cases, it is recommended to start the application from a command prompt.

Caution

To improve stability, the application is built in onedir mode instead of onefile mode.
Therefore, the entire dist/LeafShapeTool/ folder must be distributed together.

Distributing only LeafShapeTool.exe will not work properly.

About the SAM2 Module

When building from the spec file, the Segment Anything Model 2 (SAM2) (Ravi et al. 2024) module is not included by default.
To enable SAM2, follow the steps in the next section.

Enabling the SAM2 Module

To reduce file size, build time, and dependency complexity, the SAM2 folder is excluded from the default build.
However, the executable distributed on the Releases page already includes SAM2.

To enable SAM2 manually, follow the steps below.

1. Clone the SAM2 Repository

Clone the SAM2 repository from GitHub into the build directory:

cd dist/LeafShapeTool/
git clone https://github.com/facebookresearch/sam2.git

2. Download the SAM2 Checkpoints

The SAM2 model requires several checkpoint files. Download them manually and place them under sam2/checkpoints/.

For details, refer to the following official documentation:

Model Description - facebookresearch/sam2

If you are using macOS, Linux, or Windows with a Bash environment, you can automatically download the checkpoints with:

cd checkpoints && \
./download_ckpts.sh && \
cd ..

After this step, the SAM2 module will be available.

Current Limitations

The generated executable is quite large because PyInstaller bundles all dependencies.
We are considering alternative build systems such as Nuitka.

However, Nuitka currently has limited compatibility with PyQt, and it did not work properly in our environment.

Reference: Nuitka PyQt5 support

Useful References for Build and Error Troubleshooting

References

Ravi, Nikhila, Valentin Gabeur, Yuan-Ting Hu, Ronghang Hu, Chaitanya Ryali, Tengyu Ma, Haitham Khedr, et al. 2024. “SAM 2: Segment Anything in Images and Videos.” https://arxiv.org/abs/2408.00714.