3D-printing/OrcaSlicer
1
0
Fork 0
mirror of https://github.com/SoftFever/OrcaSlicer.git synced 2026-03-04 09:34:46 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Wiki Update part 5 (#9873)
Some checks are pending
Build all / Build All (push) Waiting to run
Details
Build all / Flatpak (push) Waiting to run
Details
Publish docs to Wiki / Publish docs to Wiki (push) Waiting to run
Details

Browse source 
* BASE

* precise wall and z moved

* PolyHoles

* Arc-fitting

* X-Y Compensation

* Elephant foot + moved images

* Update quality_settings_precision.md

* Wall generator and more

* Full Reorder

* TPMS-D bases

* Update strength_settings_infill.md

* Image Fix + Infill desc calculator

* Descriptions + image fix

Co-Authored-By: Rodrigo <162915171+RF47@users.noreply.github.com>

* Update cornering-calib.md

* minor fixes

* Wip updated

* Missing fills

* Update infill_desc_calculator.xlsx

* Update infill_desc_calculator.xlsx

* Update infill documentation and images

Removed outdated 'iso' infill images and updated 'top' infill images with new versions. Added new images for adaptive cubic and 2D honeycomb infill patterns. Updated strength_settings_infill.md to revise infill strength values, descriptions, and remove references to deleted images. Introduced documentation for 2D honeycomb infill and made minor corrections and clarifications throughout.

* Revise infill pattern documentation and add comparison table

Updated strength_settings_infill.md to clarify infill density calculation, add a comprehensive comparison table of infill patterns, and standardize terminology for strength and print time. Expanded pattern descriptions to use qualitative strength ratings instead of numeric values. Updated infill_desc_calculator.xlsx to reflect these changes.

* Indentation in  code examples

Adjusted the indentation of code blocks in the cornering calibration documentation for clarity and consistency with the rest of the document.

* Update 3D Honeycomb infill strength ratings

Adjusted the horizontal strength rating for 3D Honeycomb infill from 'Normal' to 'Normal-High' in the strength settings documentation and table. Updated the infill_desc_calculator.xlsx file to reflect these changes.

* Formatting and fix in ERS documentation

Updated headings to use consistent Markdown syntax, improved clarity in explanations, and reworded references for better readability.

* Fix wall generator doc link and filename

Updated the Home.md to reference the correct 'quality_settings_wall_generator' section and renamed the corresponding documentation file for consistency.

---------

Co-authored-by: Rodrigo <162915171+RF47@users.noreply.github.com>
This commit is contained in:
Ian Bassi 2025-06-19 23:19:48 -03:00 • committed by GitHub
parent 3e3a07a5b8
commit 4ec16fd714
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
92 changed files with 742 additions and 371 deletions
Download patch file Download diff file Expand all files Collapse all files

7
doc/developer-reference/Developers-Home.md
View file

@ -1,7 +0,0 @@
# For Developers
This is a documentation from someone exploring the code and is by no means complete or even completely accurate. Please edit the parts you might find inaccurate. This is probably going to be helpful nonetheless.
- [Preset, PresetBundle and PresetCollection](Preset-and-bundle)
- [Plater, Sidebar, Tab, ComboBox](plater-sidebar-tab-combobox)
- [Slicing Call Hierarchy](slicing-hierarchy)

196
doc/developer-reference/How-to-build.md Normal file
View file

@ -0,0 +1,196 @@
# How to Build
## Windows 64-bit
This guide is for building your Visual Studio 2022 solution for OrcaSlicer on Windows 64-bit.
### Tools Required
- [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) or Visual Studio 2019
```shell
winget install --id=Microsoft.VisualStudio.2022.Professional -e
```
- [CMake (version 3.31)](https://cmake.org/) — **⚠️ version 3.31.x is mandatory**
```shell
winget install --id=Kitware.CMake -v "3.31.6" -e
```
- [Strawberry Perl](https://strawberryperl.com/)
```shell
winget install --id=StrawberryPerl.StrawberryPerl -e
```
- [Git](https://git-scm.com/)
```shell
winget install --id=Git.Git -e
```
- [git-lfs](https://git-lfs.com/)
```shell
winget install --id=GitHub.GitLFS -e
```
> [!TIP]
> GitHub Desktop (optional): A GUI for Git and Git LFS, which already includes both tools.
> ```shell
> winget install --id=GitHub.GitHubDesktop -e
> ```
### Instructions
1. Clone the repository:
- If using GitHub Desktop clone the repository from the GUI.
- If using the command line:
1. Clone the repository:
```shell
git clone https://github.com/SoftFever/OrcaSlicer
```
2. Run lfs to download tools on Windows:
```shell
git lfs pull
```
2. Open the appropriate command prompt:
- For Visual Studio 2019:
Open **x64 Native Tools Command Prompt for VS 2019** and run:
```shell
build_release.bat
```
- For Visual Studio 2022:
Open **x64 Native Tools Command Prompt for VS 2022** and run:
```shell
build_release_vs2022.bat
```
> [!NOTE]
> If you encounter issues, you can try to uninstall ZLIB from your Vcpkg library.
3. If successful, you will find the VS 2022 solution file in:
```shell
build\OrcaSlicer.sln
```
> [!IMPORTANT]
> Make sure that CMake version 3.31.x is actually being used. Run `cmake --version` and verify it returns a **3.31.x** version.
> If you see an older version (e.g. 3.29), it's likely due to another copy in your system's PATH (e.g. from Strawberry Perl).
> You can run where cmake to check the active paths and rearrange your **System Environment Variables** > PATH, ensuring the correct CMake (e.g. C:\Program Files\CMake\bin) appears before others like C:\Strawberry\c\bin.
> [!NOTE]
> If the build fails, try deleting the `build/` and `deps/build/` directories to clear any cached build data. Rebuilding after a clean-up is usually sufficient to resolve most issues.
## macOS 64-bit
### Tools Required
- Xcode
- CMake (version 3.31.x is mandatory)
- Git
- gettext
- libtool
- automake
- autoconf
- texinfo
> [!TIP]
> You can install most of them by running:
> ```shell
> brew install gettext libtool automake autoconf texinfo
> ```
Homebrew currently only offers the latest version of CMake (e.g. **4.X**), which is not compatible. To install the required version **3.31.X**, follow these steps:
1. Download CMake **3.31.7** from: [https://cmake.org/download/](https://cmake.org/download/)
2. Install the application (drag it to `/Applications`).
3. Add the following line to your shell configuration file (`~/.zshrc` or `~/.bash_profile`):
```sh
export PATH="/Applications/CMake.app/Contents/bin:$PATH"
```
4. Restart the terminal and check the version:
```sh
cmake --version
```
5. Make sure it reports a **3.31.x** version.
> [!IMPORTANT]
> If you've recently upgraded Xcode, be sure to open Xcode at least once and install the required macOS build support.
### Instructions
1. Clone the repository:
```shell
git clone https://github.com/SoftFever/OrcaSlicer
cd OrcaSlicer
```
2. Build the application:
```shell
./build_release_macos.sh
```
3. Open the application:
```shell
open build/arm64/OrcaSlicer/OrcaSlicer.app
```
### Debugging in Xcode
To build and debug directly in Xcode:
1. Open the Xcode project:
```shell
open build/arm64/OrcaSlicer.xcodeproj
```
2. In the menu bar:
- **Product > Scheme > OrcaSlicer**
- **Product > Scheme > Edit Scheme...**
- Under **Run > Info**, set **Build Configuration** to `RelWithDebInfo`
- Under **Run > Options**, uncheck **Allow debugging when browsing versions**
- **Product > Run**
## Linux
### Using Docker (Recommended)
#### Dependencies
- Docker
- Git
#### Instructions
```shell
git clone https://github.com/SoftFever/OrcaSlicer && cd OrcaSlicer && ./DockerBuild.sh && ./DockerRun.sh
```
> [!NOTE]
> To troubleshoot common Docker-related errors, refer to the comments in
> ```shell
> DockerRun.sh
> ```
## Ubuntu
### Dependencies
All required dependencies will be installed automatically by the provided shell script, including:
- libmspack-dev
- libgstreamerd-3-dev
- libsecret-1-dev
- libwebkit2gtk-4.0-dev
- libssl-dev
- libcurl4-openssl-dev
- eglexternalplatform-dev
- libudev-dev
- libdbus-1-dev
- extra-cmake-modules
- libgtk2.0-dev
- libglew-dev
- cmake
- git
- texinfo
### Instructions
```shell
`./build_linux.sh -u` # install dependencies
`./build_linux.sh -disr` # build OrcaSlicer
```

416
doc/developer-reference/How-to-create-profiles.md Normal file
View file

@ -0,0 +1,416 @@
# Guide: Develop Profiles for OrcaSlicer
## Introduction
This guide will help you develop profiles for OrcaSlicer.
## High-level Overview
OrcaSlicer uses JSON files to store profiles. There are four types of profiles:
1. Printer model (type `machine_model`). Example: `Orca 3D Fuse1.json`
2. Printer variant (type `machine`). Example: `Orca 3D Fuse1 0.2 nozzle.json`
3. Filament (type `filament`). Example: `Generic PLA @Orca 3D Fuse1@.json`
4. Process (type `process`). Example: `0.10mm Standard @Orca 3D Fuse1 0.2.json`
Additionally, there is an overall meta file for each vendor (`Orca 3D.json`).
For easier understanding, let's consider a scenario with a printer manufacturer called `Orca 3D`. The manufacturer offers one printer model called `Fuse 1`, which supports 0.2/0.4/0.6/0.8mm nozzles and common market filaments.
In this case:
- Vendor profile: `Orca 3D`
- Printer profile: `Orca 3D Fuse1`
- Printer variant profile: `Orca 3D Fuse1 0.4 nozzle`
- Filament profile: `Generic PLA @Orca 3D Fuse1@`
- Process profile: `0.20mm Standard @Orca 3D Fuse1 0.4`
The profile name should be same as the filename without the `.json` extension in principal.
Naming conventions:
1. Vendor profile: `vendor_name.json`
2. Printer profile: `vendor_name` + `printer_name` + `.json`
3. Printer variant profile: `vendor_name` + `printer_variant_name` + `.json` (where `printer_variant_name` typically includes `printer_name` + `nozzle_diameter`)
4. Filament profile: `filament_vendor_name` + `filament_name` + " @" + `vendor_name` + `printer_name`/`printer_variant_name` + `.json`
5. Process profile: `layer_height` + `preset_name` + " @" + `vendor_name` + `printer_name`/`printer_variant_name` + `.json` (`preset_name` typically includes "standard," "fine," "fast," "draft," etc.)
## File Structure and Templates
Profiles should be structured in the following way under the OrcaSlicer installation directory:
```plaintext
resources\profiles\
├── Orca 3D.json
└── Orca 3D\
├── machine\
│ ├── Orca 3D Fuse1.json
│ ├── Orca 3D Fuse1 0.2 nozzle.json
│ └── Orca 3D Fuse1 0.4 nozzle.json
├── process\
│ ├── 0.10mm Standard @Orca 3D Fuse1 0.2.json
│ └── 0.20mm Standard @Orca 3D Fuse1 0.4.json
└── filament\
└── Generic PLA @Orca 3D Fuse1@.json
```
> [!TIP]
> Use short vendor names in filenames to avoid excessive length.
> [!NOTE]
> Filament profiles are **optional**. Create them only if the vendor has specifically tuned profiles for the given printer. See [Filament profiles](#filament-profiles) for details.
Template files for profiles are available in:
```shell
OrcaSlicer\resources\profiles_template\Template
```
These templates can be used as a starting point for new printer, filament, and process profiles.
## Filament Profiles
OrcaSlicer features a global filament library called `OrcaFilamentLibrary`, which is automatically available for all printers. It includes generic filaments like `Generic PLA @System` and `Generic ABS @System` etc.
Printer vendors can override specific filaments in the global library for certain printer models by creating new filament profiles.
Relationship diagram:
```mermaid
graph TD;
OrcaFilamentLibrary-->Orca_3D_filament;
OrcaFilamentLibrary-->Vendor_A_filament;
OrcaFilamentLibrary-->Vendor_B_filament;
```
> [!IMPORTANT]
> Create new filament profiles only if you have truly specifically tuned the filament for the given printer. Otherwise, use the global library. The global library has a better chance to receive optimizations and updates from OrcaSlicer contributors, which will benefit users of all printers.
### Adding Filament Profiles to the Global Library
In this section, we will discuss how to add a new filament profile into the global library.
If you want to add a new generic profile into the global library, you need to create a new file in the `resources\profiles\OrcaFilamentLibrary\filament` folder. If a base type already exists in the global library, you can use this file as a base profile by inheriting it.
The following sample JSON file shows how to create a new generic filament profile `Generic PLA-GF @System` in the global library.
1. The first step is to create a new file in the `resources\profiles\OrcaFilamentLibrary\filament` folder. The file name should be `Generic PLA-GF @System.json`. Please note that we leave the `compatible_printers` field empty so that it is available for all printers.
```json
{
"type": "filament",
"filament_id": "GFL99",
"setting_id": "GFSA05",
"name": "Generic PLA-GF @System",
"from": "system",
"instantiation": "true",
"inherits": "fdm_filament_pla",
"filament_type": ["PLA-GF"],
"filament_flow_ratio": [
"0.96"
],
"compatible_printers": []
}
```
2. Register the profile in `resources\profiles\OrcaFilamentLibrary.json`:
```json
{
"name": "OrcaFilamentLibrary",
"version": "02.02.00.04",
"force_update": "0",
"description": "Orca Filament Library",
"filament_list": [
// ...
{
"name": "Generic PLA-GF @System",
"sub_path": "filament/Generic PLA-GF @System.json"
}
]
}
```
3. The last step is to validate the newly added filament profiles see [Validate Profiles](#validate-profiles).
> [!NOTE]
> If the filament is compatible with AMS, ensure that the `filament_id` value **does not exceed 8 characters** to maintain AMS compatibility.
### Adding Filament Profiles to Printer Vendor Library
In this section, we will discuss how to add a new filament profile for a certain vendor.
If you want to add a new filament profile, whether it's a brand new profile or a specialized version of a global filament profile for a given printer, you need to create a new file in the `resources\profiles\vendor_name\filament` folder. If a base type already exists in the global library, you can use this file as a base profile by inheriting it.
Below is a sample JSON file showing how to create a specialized `Generic ABS` filament profile for the ToolChanger printer.
Please note that here we must leave the compatible_printers field non-empty, unlike in the global library.
```json
{
"type": "filament",
"setting_id": "GFB99_MTC_0",
"name": "Generic ABS @MyToolChanger",
"from": "system",
"instantiation": "true",
"inherits": "Generic ABS @System",
"filament_cooling_final_speed": [
"3.5"
],
"filament_cooling_initial_speed": [
"10"
],
"filament_cooling_moves": [
"2"
],
"filament_load_time": [
"10.5"
],
"filament_loading_speed": [
"10"
],
"filament_loading_speed_start": [
"50"
],
"filament_multitool_ramming": [
"1"
],
"filament_multitool_ramming_flow": [
"40"
],
"filament_stamping_distance": [
"45"
],
"filament_stamping_loading_speed": [
"29"
],
"filament_unload_time": [
"8.5"
],
"filament_unloading_speed": [
"100"
],
"compatible_printers": [
"MyToolChanger 0.4 nozzle",
"MyToolChanger 0.2 nozzle",
"MyToolChanger 0.6 nozzle",
"MyToolChanger 0.8 nozzle"
]
}
```
> [!NOTE]
> If the filament is compatible with AMS, ensure that the `filament_id` value **does not exceed 8 characters** to maintain AMS compatibility.
## Process Profiles
Process profiles define print quality and behavior. They follow a structure similar to filament profiles:
- A common base file, e.g., `fdm_process_common.json`, acts as the parent.
- Vendor-specific process profiles should inherit from the base using the `inherits` field.
- Profiles are stored under:
```shell
resources\profiles\vendor_name\process\
```
- **There are no global process profiles**.
- Each process profile includes a `"compatible_printers"` field with an array of compatible printer variant names.
Example:
```json
{
"type": "process",
"name": "0.10mm Standard @ExampleVendor Printer 0.2",
"inherits": "fdm_process_common",
"from": "system",
"instantiation": "true",
"compatible_printers": [
"ExampleVendor Printer 0.2 nozzle"
]
}
```
## Printer Model Profiles
- Printer model profiles (type `machine_model`) describe the general printer information.
- Example fields: `nozzle_diameter`, `bed_model`, `bed_texture`, `model_id`, etc.
- Stored in:
```shell
resources\profiles\vendor_name\machine\
```
- Each vendor's folder may contain an image named:
```shell
[machine_model_list.name]_cover.png
```
This image will be used in the UI.
Example model profile:
```json
{
"type": "machine_model",
"name": "Example M5",
"nozzle_diameter": "0.2;0.25;0.4;0.6",
"bed_model": "M5-Example-bed.stl",
"bed_texture": "M5-Example-texture.svg",
"model_id": "V1234",
"family": "Example",
"machine_tech": "FFF",
"default_materials": "Example Generic PLA;Example Generic PETG"
}
```
## Printer Variant Profiles
- Printer variants (type `machine`) define specific nozzle configurations and mechanical details.
- Each variant must inherit from a common base like `fdm_machine_common.json`.
- Must list the compatible nozzle diameter in the `nozzle_diameter` array.
- Example fields include `printer_model`, `printer_variant`, `default_print_profile`, `printable_area`, etc.
Example variant profile:
```json
{
"type": "machine",
"name": "Example M5 0.2 nozzle",
"inherits": "fdm_machine_common",
"from": "system",
"setting_id": "GM001",
"instantiation": "true",
"nozzle_diameter": ["0.2"],
"printer_model": "Example M5",
"printer_variant": "0.2",
"default_filament_profile": ["Example Generic PLA"],
"default_print_profile": "0.10mm Standard 0.2mm nozzle @Example",
"printable_area": ["0x0", "235x0", "235x235", "0x235"],
"nozzle_type": "brass"
}
```
## Models
- The `model` directory under the vendor folder is intended to behave similarly to `machine` profiles.
- Used for additional printer-related 3D models or definitions, stored at:
```
resources\profiles\vendor_name\model\
```
## Vendor Meta File
Each vendor must include a JSON file in the `resources\profiles` directory, named `vendor_name.json`. This file lists all available models, variants, processes, and filaments:
Example:
```json
{
"name": "ExampleVendor",
"version": "01.00.00.00",
"force_update": "1",
"description": "Example configuration",
"machine_model_list": [
{
"name": "Example M5",
"sub_path": "machine/Example M5.json"
}
],
"machine_list": [
{
"name": "fdm_machine_common",
"sub_path": "machine/fdm_machine_common.json"
}
],
"process_list": [
{
"name": "fdm_process_common",
"sub_path": "process/fdm_process_common.json"
}
],
"filament_list": [
{
"name": "fdm_filament_common",
"sub_path": "filament/fdm_filament_common.json"
}
]
}
```
## Validate Profiles
You can validate your profiles using both the **OrcaSlicer profile validator** and the **Python validation script**. These tools are designed to check different aspects of the profiles, so both should be executed and pass without errors to ensure full compatibility.
> [!NOTE]
> **✅ Recommendation:** Always run **both** the OrcaSlicer validator and the Python script to ensure all aspects of the profiles are valid.
### 1. OrcaSlicer Profile Validator
You can run OrcaSlicer to verify if the filament you just added is available and usable. You can also use the [Orca profile validator](https://github.com/SoftFever/Orca_tools/releases/tag/1) tool to help debug any errors.
> [!IMPORTANT]
> You need to delete the `%appdata%/OrcaSlicer/system` folder to force OrcaSlicer to reload your lastest changes.
The process is the same if you want to add a new brand filament profile into the global library. You need to create a new file in the `resources\profiles\OrcaFilamentLibrary\filament\brand_name` folder. The only difference is that you should put the file into the brand's own subfolder.
#### Usage
```shell
-h [ --help ] help
-p [ --path ] arg profile folder
-v [ --vendor ] arg Vendor name. Optional, all profiles present in the folder will be validated if not specified
-l [ --log_level ] arg (=2) Log level. Optional, default is 2 (warning). Higher values produce more detailed logs.
```
#### Example
```shell
./OrcaSlicer_profile_validator -p ~/codes/OrcaSlicer/resources/profiles -l 2 -v Custom
```
#### Sample result with errors
```shell
PS D:\codes\OrcaSlicer> ."D:/codes/OrcaSlicer/build/src/Release/OrcaSlicer_profile_validator.exe" --path d:\codes\OrcaSlicer\resources\profiles -l 2 -v Custom
[2024-02-28 21:23:06.102138] [0x0000a4e8] [error] Slic3r::ConfigBase::load_from_json: parse d:\codes\OrcaSlicer\resources\profiles/Custom/machine/fdm_klipper_common.json got a nlohmann::detail::parse_error, reason = [json.exception.parse_error.101] parse error at line 9, column 38: syntax error while parsing object - unexpected string literal; expected '}'
...
Validation failed
```
#### Sample result with success
```shell
PS D:\codes\OrcaSlicer\build\src\RelWithDebInfo> ."D:/codes/OrcaSlicer/build/src/Release/OrcaSlicer_profile_validator.exe" --path d:\codes\OrcaSlicer\resources\profiles -l 2 -v Custom
Validation completed successfully
```
> [!WARNING]
> Use `OrcaSlicer_profile_validator` on Ubuntu and `OrcaSlicer_profile_validator.exe` on Windows.
---
### 2. Python Profile Validation Script
In addition to the Orca validator, you should run the `orca_extra_profile_check.py` script. This script performs additional checks like:
- Validation of `compatible_printers` in filament profiles
- Consistency of filament names
- Validation of default materials in machine profiles (optional)
#### Example command
```shell
python ./orca_extra_profile_check.py
```
You can also enable or disable specific checks:
- `--vendor` (optional): checks only the specified vendor. If omitted, all vendors are checked.
- `--check-filaments` (enabled by default): checks `compatible_printers` fields in filament profiles
- `--check-materials`: checks default material names in machine profiles
#### Sample usage with all checks enabled
```shell
python ./orca_extra_profile_check.py --vendor="vendor_name" --check-filaments --check-materials
```
The script will output the number of errors found and exit with a non-zero status code if any issues are detected.

246
doc/developer-reference/How-to-wiki.md Normal file
View file

@ -0,0 +1,246 @@
# How to Contribute to the Wiki
This guide explains how to contribute to the Orca Slicer wiki.
Orca Slicer uses GitHub's wiki feature, which allows users and developers to create and edit documentation collaboratively.
We encourage all developers and users to contribute to the wiki by updating existing pages and adding new content. This helps keep the documentation up-to-date and useful for everyone.
When developing new features, please consider updating the wiki to reflect these changes. This ensures that users have access to the latest information and can make the most of the features.
- [Wiki Structure](#wiki-structure)
- [Home](#home)
- [Index and Navigation](#index-and-navigation)
- [File Naming and Organization](#file-naming-and-organization)
- [Formatting and Style](#formatting-and-style)
- [Markdown Formatting](#markdown-formatting)
- [Alerts and Callouts](#alerts-and-callouts)
- [Images](#images)
- [Image Naming](#image-naming)
- [Image Placement](#image-placement)
- [Linking Images](#linking-images)
- [Examples](#examples)
- [Avoid the Following](#avoid-the-following)
- [Resize Images](#resize-images)
- [Image Cropping and Highlighting](#image-cropping-and-highlighting)
- [Recommended Formats](#recommended-formats)
- [Structuring Content](#structuring-content)
- [Commands and Code Blocks](#commands-and-code-blocks)
- [External Links](#external-links)
## Wiki Structure
Each wiki page is a Markdown file located in the `doc` directory of the repository. The wiki is organized into various sections, each covering different areas of the project.
### Home
The starting point of the Orca Slicer wiki is the **Home** page. From there, you can navigate to different sections and topics related to the project.
When creating a new page or section, be sure to link it from the Home page under the appropriate category.
- **Print Settings:** Detailed explanations of print settings, tips, and tricks for optimizing print quality.
- **Printer Calibration:** Step-by-step calibration tests in Orca Slicer, including how to interpret the results.
- **Developer Section:** Information for developers and contributors on building Orca Slicer, localization, and developer resources.
#### Index and Navigation
Github Wiki uses the name of the files as identifiers for the pages. To link to a page, use the file name without the `.md` extension.
If the file is inside a subdirectory, dont include the subdirectory in the link. Instead, link directly to the file from the Home page.
For example, if you create a new page `doc/calibration/flow-rate-calib.md`, link it as follows:
```markdown
[Calibration Guide](Calibration)
```
For pages with extensive content, it's helpful to include a table of contents at the beginning. This allows users to quickly find and access different sections of the page.
```markdown
- [Wiki Structure](#wiki-structure)
- [Home](#home)
- [Index and Navigation](#index-and-navigation)
- [File Naming and Organization](#file-naming-and-organization)
- [Formatting and Style](#formatting-and-style)
```
> [!NOTE]
> If you're adding a new section, follow the existing structure and ensure it doesn't already fit within an existing category. Link it from the Home page accordingly.
### File Naming and Organization
When creating new pages, follow these file naming conventions:
- Use unique file names to avoid conflicts.
- Use descriptive names that reflect the page's content.
- Use kebab-case for filenames (e.g., `How-to-wiki.md`).
- If the page belongs to a specific section, include the section name in the file name. For example, calibration pages should end with `-calib.md` (e.g., `flow-rate-calib.md`, `pressure-advance-calib.md`).
- Place files in the appropriate subdirectory when applicable (e.g., `doc/calibration/` for calibration-related content).
## Formatting and Style
Please adhere to the following style and formatting conventions when contributing to the wiki.
### Markdown Formatting
The wiki uses standard Markdown syntax for formatting and aims to maintain a consistent style across all pages. Avoid using raw HTML tags and prefer Markdown formatting instead.
Ensure your indentation is consistent, especially for code blocks and lists.
Refer to the [GitHub Markdown Guide](https://guides.github.com/features/mastering-markdown/) for more information on Markdown syntax.
### Alerts and Callouts
To add alerts or notes, use GitHub’s Markdown alert syntax:
```markdown
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
Refer to the [GitHub Alert Guide](https://docs.github.com/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) for more details.
## Images
Images are encouraged to enhance the clarity and quality of the wiki content. They help illustrate concepts, provide examples, and improve readability.
> [!CAUTION]
> Do not use images from third-party sources unless you have the proper permissions.
### Image Naming
- Use clear, descriptive filenames that reflect the image content.
- For section-specific images, include the section name or initials. For example, images related to Pressure Advance could be named `pa-[description].png`.
### Image Placement
- General images should be placed in the `doc/images/` directory.
- Section-specific images should be stored in their corresponding subdirectories (e.g., `doc/images/calibration/` for calibration content).
### Linking Images
Always use raw GitHub URLs for image links to ensure correct display:
Format = `![[filename]](` + Base URL + filename.extension + Raw tag + `)`
- Base URL:
```markdown
https://github.com/SoftFever/OrcaSlicer/blob/main/doc/images/
```
- Raw tag:
```markdown
?raw=true
```
#### Examples
- For an image in `doc/images/` named `example.png`:
```markdown
![example](https://github.com/SoftFever/OrcaSlicer/blob/main/doc/images/example.png?raw=true)
```
- For an image in a subdirectory like `doc/images/calibration/pa-example.svg`:
```markdown
![pa-example](https://github.com/SoftFever/OrcaSlicer/blob/main/doc/images/calibration/pa-example.svg?raw=true)
```
> [!IMPORTANT]
> New or Moved Images will not appear in the preview until the Pull Request is merged. Double-check your paths.
> If you are changing an image path, ensure all links to that image are updated accordingly.
#### Avoid the Following
- Relative paths
- GitHub Assets, user content, or user-images URLs
- External image links from unreliable or temporary platforms
- Images containing personal or sensitive information
- Using images for content that can be expressed in text, such as equations or code—use Markdown syntax or Mermaid/Math formatting instead.
> [!NOTE]
> When contributing section-specific images, follow the naming conventions and directory structure.
#### Resize Images
Avoid the resize of images and let the Wiki handle it automatically.
If resizing is necessary (e.g., for thumbnails), use the following syntax:
HTML Format = `<img src="` + Base URL + filename.extension + Raw tag + `" alt="` + filename + `"` + size limit.
Example:
```html
<img src="https://github.com/SoftFever/OrcaSlicer/blob/main/doc/images/InputShaping/IS_damp_marlin_print_measure.jpg?raw=true" alt="Input_Shaping" height="200">
```
### Image Cropping and Highlighting
To ensure clarity:
- Crop images to focus on relevant areas.
- Use annotations like arrows or shapes (circles, rectangles) to highlight key parts—but avoid overloading the image.
### Recommended Formats
- **JPG:** Suitable for photographs. Avoid for images with text or fine detail due to compression artifacts.
- **PNG:** Ideal for screenshots or images with transparency. Ensure sufficient contrast for light and dark modes.
- **SVG:** Preferred when possible. SVGs support theme adaptation (light/dark mode), making them ideal for icons and diagrams.
## Structuring Content
Each wiki page should have a clear objective, which helps determine the structure of the content. After a brief introduction, use one of the following formats:
- **Step-by-Step Guide:** Organize content into sections and subsections for tasks requiring sequential actions (e.g., calibration procedures).
- **GUI-Based Reference:** If sequence isn’t crucial, structure the content following Orca Slicer’s GUI. This format works well for configurable settings or feature overviews.
- Example: Explain **Layer Height** before **Initial Layer Height**, as the former applies globally while the latter is specific to the first layer.
## Commands and Code Blocks
When adding commands or code blocks please use the [Code Block with Syntax Highlighting feature of Markdown](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#syntax-highlighting).
- Use triple backticks (```) to enclose code blocks.
- Specify the language for proper highlighting and readability.
````markdown
```json
{
"key": "value"
}
```
````
```json
{
"key": "value"
}
```
## External Links
Be careful when linking to external resources. Ensure that the links are relevant and reliable.
Papers, articles, and other resources should be cited properly.

108
doc/developer-reference/Localization_guide.md Normal file
View file

@ -0,0 +1,108 @@
# Localization and translation guide
The purpose of this guide is to describe how to contribute to the Orca Slicer translations. We use GNUgettext for extracting string resources from the project and PoEdit for editing translations.
Those can be downloaded here:
- https://sourceforge.net/directory/os:windows/?q=gnu+gettext GNUgettext package contains a set of tools to extract strings from the source code and to create the translation Catalog.
- https://poedit.net PoEdit provides good interface for the translators.
After GNUgettext is installed, it is recommended to add the path to gettext/bin to PATH variable.
Full manual for GNUgettext can be seen here: http://www.gnu.org/software/gettext/manual/gettext.html
### Scenario 1. How do I add a translation or fix an existing translation
1. Get PO-file 'OrcaSlicer_xx.pot' from corresponding sub-folder here:
https://github.com/softfever/OrcaSlicer/tree/master/localization/i18n
2. Open this file in PoEdit as "Edit a translation"
3. Apply your corrections to the translation
4. Push changed OrcaSlicer_xx.po into the original folder
5. copy OrcaSlicer_xx.mo into resources/i18n/xx and rename it to OrcaSlicer.mo, then push the changed file.
### Scenario 2. How do I add a new language support
1. Get file OrcaSlicer.pot here :
https://github.com/softfever/OrcaSlicer/tree/master/localization/i18n
2. Open it in PoEdit for "Create new translation"
3. Select Translation Language (for example French).
4. As a result you will have fr.po - the file containing translation to French.
Notice. When the translation is complete you need to:
- Rename the file to OrcaSlicer_fr.po
- Click "Save file" button. OrcaSlicer_fr.mo will be created immediately
- Bambu_Studio_fr.po needs to be copied into the sub-folder fr of https://github.com/softfever/OrcaSlicer/tree/master/localization/i18n, and be pushed
- copy OrcaSlicer_xx.mo into resources/i18n/xx and rename it to OrcaSlicer.mo, then push the changed file.
( name of folder "fr" means "French" - the translation language).
### Scenario 3. How do I add a new text resource when implementing a feature to Orca Slicer
Each string resource in Orca Slicer available for translation needs to be explicitly marked using L() macro like this:
```C++
auto msg = L("This message to be localized")
```
To get translated text use one of needed macro/function (`_(s)` or `_CHB(s)` ).
If you add new file resource, add it to the list of files containing macro `L()`
### Scenario 4. How do I use GNUgettext to localize my own application taking Orca Slicer as an example
1. For convenience create a list of files with this macro `L(s)`. We have
https://github.com/softfever/OrcaSlicer/blob/master/localization/i18n/list.txt.
2. Create template file(*.POT) with GNUgettext command:
```shell
xgettext --keyword=L --add-comments=TRN --from-code=UTF-8 --debug -o OrcaSlicer.pot -f list.txt
```
Use flag `--from-code=UTF-8` to specify that the source strings are in UTF-8 encoding
Use flag `--debug` to correctly extract formatted strings(used %d, %s etc.)
3. Create PO- and MO-files for your project as described above.
4. To merge old PO-file with strings from created new POT-file use command:
```shell
msgmerge -N -o new.po old.po new.pot
```
Use option `-N` to not using fuzzy matching when an exact match is not found.
5. To concatenate old PO-file with strings from new PO-file use command:
```shell
msgcat -o new.po old.po
```
6. Create an English translation catalog with command:
```shell
msgen -o new.po old.po
```
Notice, in this Catalog it will be totally same strings for initial text and translated.
When you have Catalog to translation open POT or PO file in PoEdit and start translating.
## General guidelines for Orca Slicer translators
- We recommend using _PoEdit_ application for translation (as described above). It will help you eliminate most punctuation errors and will show you strings with "random" translations (if the fuzzy parameter was used).
- To check how the translated text looks on the UI elements, test it :) If you use _PoEdit_, all you need to do is save the file. At this point, a MO file will be created. Rename it Orca Slicer.mo, and you can run Orca Slicer (see above).
- If you see an encoding error (garbage characters instead of Unicode) somewhere in Orca Slicer, report it. It is likely not a problem of your translation, but a bug in the software.
- See on which UI elements the translated phrase will be used. Especially if it's a button, it is very important to decide on the translation and not write alternative translations in parentheses, as this will significantly increase the width of the button, which is sometimes highly undesirable:
- If you decide to use autocorrect or any batch processing tool, the output requires very careful proofreading. It is very easy to make it do changes that break things big time.
- **Any formatting parts of the phrases must remain unchanged.** For example, you should not change `%1%` to `%1 %`, you should not change `%%` to `%` (for percent sign) and similar. This will lead to application crashes.
- Please pay attention to spaces, line breaks (\n) and punctuation marks. **Don't add extra line breaks.** This is especially important for parameter names.
- Description of the parameters should not contain units of measurement. For example, "Enable fan if layer print time is less than ~~n seconds~~"
- For units of measurement, use the international system of units. Use "s" instead of "sec".
- If the phrase doesn't have a dot at the end, don't add it. And if it does, then don't forget to :)
- It is useful to stick to the same terminology in the application (especially with basic terms such as "filament" and similar). Stay consistent. Otherwise it will confuse users.

5
doc/developer-reference/plater-sidebar-tab-combobox.md
View file

@ -1,6 +1,9 @@
# Application Structure Overview
### !! incomplete, possibly inaccurate, being updated with new info !!
WIP...
> [!WARNING]
> !! incomplete, possibly inaccurate, being updated with new info !!
## [`Plater`](https://github.com/SoftFever/OrcaSlicer/blob/main/src/slic3r/GUI/Plater.hpp)