Installation and Setup

Prerequisites

• Python: Version 3.11 or later.
• IDE: Visual Studio Code is recommended.
• Git: Either Git (command line) or GitHub Desktop.

Creating a Virtual Environment in VS Code

1. Open the C2F4DT folder in VS Code.
2. Open the terminal (`Ctrl+``).
3. Create a virtual environment:

   python -m venv venv_c2f4dt
   

4. Activate the environment:
5. On macOS/Linux:

   source venv_c2f4dt/bin/activate
   

6. On Windows:

   venv_c2f4dt\Scripts\activate
   

VS Code should auto-detect the venv_c2f4dt. If not, select it manually (Python: Select Interpreter).

Installing Packages

Once the environment is active, install dependencies:

pip install --upgrade pip
pip install -r requirements.txt

Activating in Regular or Development Mode

Regular Mode

To activate the application in regular mode, run:

pip install .

Development Mode

For development mode, which includes additional tools and dependencies for development, run:

pip install -e .[dev]

You can also activate in user mode (without requiring administrative privileges):

pip install --user .

Running the Application

• To launch the main app:

  python main.py
  

• Or run example scripts:

  python examples/run_app.py
  

---

Version Control with Git

Cloning the Repository

git clone https://github.com/gcastellazzi/C2F4DT.git
cd C2F4DT

If using GitHub Desktop, choose “Clone repository” and paste the repo URL.

Creating a Branch

Always create a feature branch before editing:

git checkout -b feature/my-change

Making Commits

• Keep commits small and focused.
• Use descriptive messages:

  git commit -m "fix: corrected normals orientation in slice viewer"
  

• Do not commit:
• venv_c2f4dt/
• large datasets
• build artifacts

Make sure .gitignore includes venv_c2f4dt/, __pycache__/, and site/.

Pushing Changes

git push origin feature/my-change

Then open a Pull Request on GitHub.