From 8e6f00a2a5065516d61e63dc53fd6a9536ce6f40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rene=20P=C3=B6schl?= Date: Tue, 18 Aug 2020 21:41:31 +0200 Subject: [PATCH] Update 3d Model Contribution Guidelines * Clarify restrictions for third party contributions (M1.1) * Remove rule M1.2 as it implied models provided by manufacturers are preferred * Clarify what counts as source files and add note about script contributions (M1.3) * Clarify that all contributions must be made with both wrl and step models (M2.1) * Clarify that Freecad is the preferred design tool (M2.3) --- content/klc/M1.1.adoc | 10 +++++++--- content/klc/M1.2.adoc | 13 ++----------- content/klc/M1.3.adoc | 11 +++++++---- content/klc/M2.1.adoc | 10 ++-------- content/klc/M2.2.adoc | 8 +++++--- content/klc/M2.3.adoc | 11 +++++++++++ content/libraries/klc.adoc | 2 +- content/libraries/klc_history.adoc | 8 ++++++++ 8 files changed, 43 insertions(+), 30 deletions(-) create mode 100644 content/klc/M2.3.adoc diff --git a/content/klc/M1.1.adoc b/content/klc/M1.1.adoc index b344047b..fa3cc1a5 100644 --- a/content/klc/M1.1.adoc +++ b/content/klc/M1.1.adoc @@ -1,7 +1,11 @@ +++ -brief = "Models should be created by contributor" +brief = "The contributor must own the rights to share the 3D model" +++ -Users should only submit models they have created themselves, either manually designed or via parametric scripting tools. +The goal of the KiCad 3d model library is to provide a free open library of 3d models. This requires certain restrictions regarding contributions with respect to their legal status. -Contributing model data designed by a third party complicates licensing issues and should be avoided. \ No newline at end of file +* Users must only submit models for which they own the rights allowing relicensing under the KiCad library licence. + +* In most cases this means they have created the model themselves, either manually designed in a parametric modeling software or via scripting tools. + +* Contributing model data designed by a third party complicates licensing issues and is to be avoided. This includes files downloaded from a manufacturers website. \ No newline at end of file diff --git a/content/klc/M1.2.adoc b/content/klc/M1.2.adoc index ed12eac9..32dde0b7 100644 --- a/content/klc/M1.2.adoc +++ b/content/klc/M1.2.adoc @@ -1,14 +1,5 @@ +++ -brief = "Manufacturer models should not be duplicated" +brief = "Withdrawn" +++ -If a manufacturer provides 3D model data for download from its website, these models should not be duplicated in the KiCad library. - -A link to the manufacturer model files may be added to the `README.md` file within the 3D model directory. - -**Exception:** - -If 3D model data provided by a manufacturer is of low quality or not available for public download, then these data may be added if the following criteria are met: - -* The contributor is the creator of the model data -* The contributed files provide some advantage over the data supplied by the manufacturer \ No newline at end of file +This rule was withdrawn. diff --git a/content/klc/M1.3.adoc b/content/klc/M1.3.adoc index d8f0e4c3..092b4442 100644 --- a/content/klc/M1.3.adoc +++ b/content/klc/M1.3.adoc @@ -1,11 +1,14 @@ +++ -brief = "Source files for 3D models should be supplied" +brief = "Source files for 3D models must be supplied" +++ The KiCad library maintains a repository for 3D source files at link:https://github.com/kicad/kicad-packages3d-source[https://github.com/kicad/kicad-packages3d-source]. -The _source files_ used to generate 3D model data should be submitted to this repository when a user contributes 3D model data. +The _source files_ used to generate 3D model data must be submitted to this repository when a user contributes 3D model data. -Source files include file generator scripts, or native model files from source software (e.g. FreeCAD). +* Source files of 3d models are the native files generated by the 3d modeling software (Example: fcstd for Freecad). -The source repository directory structure mirrors that of the kicad-packages-3d repository. +* Source files alternatively are any generator scripts. +** However scripts found in link:https://github.com/easyw/kicad-3d-models-in-freecad[https://github.com/easyw/kicad-3d-models-in-freecad] do not need to be added to the source repo. + +* The source repository directory structure mirrors that of the kicad-packages-3d repository. diff --git a/content/klc/M2.1.adoc b/content/klc/M2.1.adoc index 6125d11f..b9aec4a2 100644 --- a/content/klc/M2.1.adoc +++ b/content/klc/M2.1.adoc @@ -1,19 +1,13 @@ +++ -brief = "Permitted 3D model file types" +brief = "3D models must be supplied in both 'step' and 'wrl' formats" +++ -The KiCad 3D model library supports two file formats: +Any 3D model contribution to the KiCad library must be made in both step and wrl format. **WRL** * WRL files contain material properties and are used for realistic rendering. However they cannot be exported to MCAD packages. -* KiCad v4.x and lower can only render WRL files **STEP** * STEP files are used for integration with MCAD software packages. These files do not contain material properties and cannot be used for realistic rendering. -* KiCad v5.x and above can render STEP files directly in the 3D viewer - -Only models provided in these file formats will be accepted. - -It is suggested that a .WRL and .STEP version of the model are provided simultaneously. This provides options for both high quality rendering and MCAD integration. diff --git a/content/klc/M2.2.adoc b/content/klc/M2.2.adoc index 9884b8c2..00980af5 100644 --- a/content/klc/M2.2.adoc +++ b/content/klc/M2.2.adoc @@ -10,9 +10,11 @@ The 3D model must be aligned such that it does not require an additional alignme **Scaling** -. STEP files include absolute dimensional information, and _should never have a secondary scaling factor applied_. The model `scaling` parameter in KiCad must read (`1`, `1`, `1`) -. WRL files do not specify absolute dimensions. KiCad normalizes model parameters to units of _inches_ and the internal units (dimensionless) of the WRL model must be scaled accordingly. +. STEP files include absolute dimensional information, and _must never have a secondary scaling factor applied_. The model `scaling` parameter in KiCad must read (`1`, `1`, `1`) +. WRL files do not specify absolute dimensions. The WRL fileformat has no way do specify what its units mean. KiCad considers one WRL unit to be 0.1 inches for historical reasons, so models must be scaled accordingly. +.. Assuming the model is designed in `mm` then the required scaling factor for WRL export is `1/2.54` (~0.393700787). +.. The Freecad extension _kicad-stepup_ exports WRL files already correctly scaled. **Rotation** -The model should be rotated such that no additional rotation is required within KiCad to align the 3D model with the footprint. \ No newline at end of file +The model must be rotated such that no additional rotation is required within KiCad to align the 3D model with the footprint. diff --git a/content/klc/M2.3.adoc b/content/klc/M2.3.adoc new file mode 100644 index 00000000..f528b85b --- /dev/null +++ b/content/klc/M2.3.adoc @@ -0,0 +1,11 @@ ++++ +brief = "Freecad is the preferred design tool" ++++ + +The goal of the KiCad 3d model library is to provide a free open library of 3d models. The use of open source design tools is preferred for this very reason. + +Freecad is chosen as the preferred tool to be used. Especially in combination with the kicad-stepup extension. + +Good alternatives are open scripting options like OpenSCAD or CadQuery. For the latter consider contributing to link:https://github.com/easyw/kicad-3d-models-in-freecad[https://github.com/easyw/kicad-3d-models-in-freecad] + +Files created in closed source tools are permitted. If a certain model is available designed in both an open and closed tool then the one from the open tool is preferred and will replace the other one. \ No newline at end of file diff --git a/content/libraries/klc.adoc b/content/libraries/klc.adoc index 86171672..9daff37b 100644 --- a/content/libraries/klc.adoc +++ b/content/libraries/klc.adoc @@ -14,7 +14,7 @@ summary = "The KiCad Library Convention (KLC) is a set of requirements for contr toc::[] -**link:/libraries/klc/history/[Revision: 3.0.26]** +**link:/libraries/klc/history/[Revision: 3.0.28]** --- diff --git a/content/libraries/klc_history.adoc b/content/libraries/klc_history.adoc index cbc736cb..2c805b3c 100644 --- a/content/libraries/klc_history.adoc +++ b/content/libraries/klc_history.adoc @@ -5,6 +5,14 @@ summary = "Revision history of the KiCad Library Conventions" +++ --- +== 3.0.28 - 2020-09-18 +* Rework ruleset for 3d model contributions + * Clarify restrictions for third party contributions (M1.1) + * Remove rule M1.2 as it implied models provided by manufacturers are preferred + * Clarify what counts as source files and add note about script contributions (M1.3) + * Clarify that all contributions must be made with both wrl and step models (M2.1) + * Clarify that Freecad is the preferred design tool (M2.3) + == 3.0.27 - 2020-09-12 * Change general guidelines (G) to mention templates and 3D models