Scripts/pl: Difference between revisions

From FreeCAD Documentation
(Created page with "Kilka przykładów może pomóc, usuń całą linię po metodzie {{incode|base_cyl}} i wstaw poniższy fragment kodu:")
(Created page with "To jest kompletny przykład kodu z przyzwoitym skryptem docstring zgodnie z konwencją [https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google Google docstrings]:")
 
(35 intermediate revisions by 2 users not shown)
Line 22: Line 22:
Niestety informacje na temat skryptów w dokumentacji, a nawet na tej Wiki, są rozproszone i brakuje im jednolitości "pisania”, a większość z nich jest wyjaśniona w zbyt techniczny sposób.
Niestety informacje na temat skryptów w dokumentacji, a nawet na tej Wiki, są rozproszone i brakuje im jednolitości "pisania”, a większość z nich jest wyjaśniona w zbyt techniczny sposób.


<span id="Whetting_your_appetite"></span>
<span id="Getting_started"></span>
==Zaostrzenie apetytu==
==Rozpoczęcie pracy==


Pierwszą przeszkodą w łatwej drodze do tworzenia skryptów jest to, że nie ma bezpośredniego sposobu na dostęp do wewnętrznego edytora Python FreeCAD poprzez pozycję menu lub ikonę na pasku narzędzi, ale wiedząc, że FreeCAD otwiera plik z rozszerzeniem {{incode|.py}} w wewnętrznym edytorze Python, najprostszą sztuczką jest utworzenie go w ulubionym edytorze tekstu, a następnie otwarcie go za pomocą zwykłego polecenia {{MenuCommand|Plik → Otwórz}}.
Pierwszą przeszkodą w łatwej drodze do tworzenia skryptów jest to, że nie ma bezpośredniego sposobu na dostęp do wewnętrznego edytora Python FreeCAD poprzez pozycję menu lub ikonę na pasku narzędzi, ale wiedząc, że FreeCAD otwiera plik z rozszerzeniem {{incode|.py}} w wewnętrznym edytorze Python, najprostszą sztuczką jest utworzenie go w ulubionym edytorze tekstu, a następnie otwarcie go za pomocą zwykłego polecenia {{MenuCommand|Plik → Otwórz}}.
Line 30: Line 30:


{{Code|code=
{{Code|code=
"""script.py
"""filename.py


A short description of what the script does
Primo script per FreeCAD


"""
"""
Line 44: Line 44:
"""filename.py
"""filename.py


First FreeCAD Script
Here a short but significant description of what the script do


"""
"""


import FreeCAD
import FreeCAD
from FreeCAD import Base, Vector
from FreeCAD import Placement, Rotation, Vector
import Part
from math import pi, sin, cos


DOC = FreeCAD.activeDocument()
DOC = FreeCAD.activeDocument()
DOC_NAME = "Pippo"
DOC_NAME = "Wiki_Example"

# Helpers methods


def clear_doc():
def clear_doc():
"""Clear activeDocument deleting all the objects."""
"""
Clear the active document deleting all the objects
"""
for obj in DOC.Objects:
for obj in DOC.Objects:
DOC.removeObject(obj.Name)
DOC.removeObject(obj.Name)


def setview():
def setview():
"""Rearrange View"""
"""Rearrange View."""
FreeCAD.Gui.SendMsgToActiveView("ViewFit")
FreeCAD.Gui.SendMsgToActiveView("ViewFit")
FreeCAD.Gui.activeDocument().activeView().viewAxometric()
FreeCAD.Gui.activeDocument().activeView().viewAxometric()
Line 75: Line 73:
clear_doc()
clear_doc()


ROT0 = Rotation(0, 0, 0)
# EPS= tolerance to use to cut the parts
VEC0 = Vector(0, 0, 0)
EPS = 0.10
EPS_C = EPS * -0.5
}}
}}


Line 83: Line 80:


* {{incode|import FreeCAD}} Ta linia importuje FreeCAD w interpreterze FreeCAD Python, może wydawać się zbędna, ale tak nie jest.
* {{incode|import FreeCAD}} Ta linia importuje FreeCAD w interpreterze FreeCAD Python, może wydawać się zbędna, ale tak nie jest.
* {{incode|from FreeCAD import Base, Vector}} Base i Vector są szeroko stosowane w skryptach FreeCAD, importowanie ich w ten sposób pozwoli zaoszczędzić na wywoływaniu ich za pomocą {{incode|FreeCAD.Vector}} lub {{incode|FreeCAD.Base}} zamiast {{incode|Base}} lub {{incode|Vector}}, zaoszczędzi to wiele naciśnięć klawiszy i sprawi, że linie kodu będą znacznie krótsze.
* {{incode|from FreeCAD import Placement, Rotation, Vector}}. '''Umiejscowienie''' '''Obrót''' i '''Wektor''' są szeroko stosowane w skryptach FreeCAD, importowanie ich w ten sposób pozwoli zaoszczędzić na wywoływaniu ich za pomocą {{incode|FreeCAD.Vector}} lub {{incode|FreeCAD.Placement}} zamiast {{incode|Vector}} lub {{incode|Placement}}, zaoszczędzi to wiele naciśnięć klawiszy i sprawi, że linie kodu będą znacznie krótsze.


Zacznijmy od małego skryptu, który wykonuje bardzo małą pracę, ale pokazuje moc tej metody.
Zacznijmy od małego skryptu, który wykonuje bardzo małą pracę, ale pokazuje moc tej metody.


{{Code|code=
{{Code|code=
# Script methods
def cubo(nome, lung, larg, alt):

obj_b = DOC.addObject("Part::Box", nome)
def my_box(name, len, wid, hei):
obj_b.Length = lung
obj_b.Width = larg
"""Create a box."""
obj_b.Height = alt
obj_b = DOC.addObject("Part::Box", name)
obj_b.Length = len
obj_b.Width = wid
obj_b.Height = hei


DOC.recompute()
DOC.recompute()
Line 100: Line 100:
# objects definition
# objects definition


obj = cubo("test_cube", 5, 5, 5)
obj = my_box("test_cube", 5, 5, 5)


setview()
setview()
}}
}}


Umieść te linie po kodzie "szablonu" i naciśnij zieloną strzałkę na pasku narzędzi "Makrodefinicje".
Wpisz powyższe linie kodu po {{incode|# Script methods}} i naciśnij zieloną strzałkę na pasku narzędzi '''Makrodefinicje'''.


Zobaczysz kilka magicznych rzeczy, otworzy się nowy dokument o nazwie "Pippo" ''(włoska nazwa '''Goofy''')'', a w widoku 3D zobaczysz [[Part_Box/pl|Sześcian]], taki jak na poniższym obrazku.
Zobaczysz kilka magicznych rzeczy, otworzy się nowy dokument o nazwie "Wiki_example", a w widoku 3D zobaczysz [[Part_Box/pl|Sześcian]], taki jak na poniższym obrazku.


[[File:Cubo.png|thumb|center|Test Cube]]
[[File:Cubo.png|thumb|center|Sześcian testowy.]]


<span id="Something_more..."></span>
<span id="Something_more"></span>
==Coś więcej ...==
==Coś więcej==


Nie jest to zbyt niesamowite? Tak, ale musimy od czegoś zacząć, możemy zrobić to samo z [[Part_Cylinder/pl|walcem]], dodając te linie kodu po metodzie {{incode|cubo()}} i przed linią: {{incode|# objects definition}}.
Nie jest to zbyt niesamowite? Tak, ale musimy od czegoś zacząć, możemy zrobić to samo z [[Part_Cylinder/pl|walcem]], dodając te linie kodu po metodzie {{incode|my_box()}} i przed linią: {{incode|# objects definition}}.


{{Code|code=
{{Code|code=
def base_cyl(nome, ang, rad, alt ):
def my_cyl(name, ang, rad, hei):
"""Create a Cylinder."""
obj = DOC.addObject("Part::Cylinder", nome)
obj = DOC.addObject("Part::Cylinder", name)
obj.Angle = ang
obj.Angle = ang
obj.Radius = rad
obj.Radius = rad
obj.Height = alt
obj.Height = hei

DOC.recompute()
DOC.recompute()


return obj
return obj

}}
}}


Line 132: Line 132:


* Brak zwykłego odniesienia do {{incode|App.}}, obecnego w wielu fragmentach kodu Dokumentacji, jest zamierzony, kod ten może być użyty nawet do wywołania FreeCAD jako modułu w zewnętrznym interpreterze Pythona, nie jest to łatwe do zrobienia z AppImage, ale z pewną ostrożnością można to zrobić. Plus w standardowym motto Pythona, że "lepiej jawnie niż niejawnie" {{incode|App.}} wyjaśnia w bardzo "kiepski" sposób, skąd pochodzą rzeczy.
* Brak zwykłego odniesienia do {{incode|App.}}, obecnego w wielu fragmentach kodu Dokumentacji, jest zamierzony, kod ten może być użyty nawet do wywołania FreeCAD jako modułu w zewnętrznym interpreterze Pythona, nie jest to łatwe do zrobienia z AppImage, ale z pewną ostrożnością można to zrobić. Plus w standardowym motto Pythona, że "lepiej jawnie niż niejawnie" {{incode|App.}} wyjaśnia w bardzo "kiepski" sposób, skąd pochodzą rzeczy.
* Zwróć uwagę na użycie "stałej" nazwy przypisanej do aktywnego Dokumentu w {{incode|DOC}} = {{incode|FreeCAD. activeDocument()}}; activeDocument nie jest "stałą" w ścisłym sensie, ale w sposób "semantyczny" jest naszym "aktywnym dokumentem", który dla naszego użytku jest właściwą "stałą", więc konwencja Pythona polega na używaniu nazwy "ALL CAPS" dla "stałych", nie wspominając o tym, że {{incode|DOC}} jest znacznie krótszy niż {{incode|FreeCAD.activeDocument()}}.
* Zwróć uwagę na użycie "stałej" nazwy przypisanej do aktywnego Dokumentu w {{incode|DOC}} &#61; {{incode|FreeCAD. activeDocument()}}; activeDocument nie jest "stałą" w ścisłym sensie, ale w sposób "semantyczny" jest naszym "aktywnym dokumentem", który dla naszego użytku jest właściwą "stałą", więc konwencja Pythona polega na używaniu nazwy "ALL CAPS" dla "stałych", nie wspominając o tym, że {{incode|DOC}} jest znacznie krótszy niż {{incode|FreeCAD.activeDocument()}}.
* Każda metoda zwraca geometrię, będzie to jasne w dalszej części strony.
* Każda metoda zwraca geometrię, będzie to jasne w dalszej części strony.
* Geometria nie miała właściwości {{incode|Placement}}, podczas używania prostych geometrii do tworzenia bardziej złożonych geometrii, zarządzanie {{incode|Placement}} jest kłopotliwe.
* Geometria nie miała właściwości {{incode|Placement}}, podczas używania prostych geometrii do tworzenia bardziej złożonych geometrii, zarządzanie {{incode|Placement}} jest kłopotliwe.
Line 138: Line 138:
Co teraz zrobić z tą geometrią?
Co teraz zrobić z tą geometrią?


Wprowadźmy operacje logiczne. Jako przykład początkowy umieść te linie po {{incode|base_cyl(...}}, to utworzy metodę dla operacji '''Fusion''' znanej również jako '''Union''':
Wprowadźmy operacje logiczne. Jako przykład początkowy umieść te linie po {{incode|my_cyl}}, to utworzy metodę dla operacji '''Fusion''' znanej również jako '''Union''':


{{Code|code=
{{Code|code=
def fuse_obj(nome, obj_0, obj_1):
def fuse_obj(name, obj_0, obj_1):
"""Fuse two objects."""
obj = DOC.addObject("Part::Fuse", nome)
obj = DOC.addObject("Part::Fuse", name)
obj.Base = obj_0
obj.Base = obj_0
obj.Tool = obj_1
obj.Tool = obj_1
Line 158: Line 159:
# objects definition
# objects definition


obj = cubo("cubo_di_prova", 5, 5, 5)
obj = my_box("test_cube", 5, 5, 5)


obj1 = base_cyl('primo cilindro', 360,2,10)
obj1 = my_cyl("test_cyl", 360, 2, 10)


fuse_obj("Fusione", obj, obj1)
fuse_obj("Fusion", obj, obj1)


setview()
setview()
Line 169: Line 170:
Uruchom skrypt za pomocą zielonej strzałki, a w widoku 3D zobaczymy coś takiego:
Uruchom skrypt za pomocą zielonej strzałki, a w widoku 3D zobaczymy coś takiego:


[[File:Cucil.png|thumb|center|cube and cylinder]]
[[File:Cucil.png|thumb|center|Sześcian i cylinder.]]


<span id="Placement"></span>
<span id="Placement"></span>
Line 180: Line 181:
FreeCAD oferuje szeroki wybór sposobów ustawiania tej właściwości, jeden jest bardziej dostosowany do drugiego w zależności od wiedzy i doświadczenia użytkownika, ale bardziej proste pisanie jest wyjaśnione w cytowanym samouczku, używa osobliwej definicji części {{incode|Rotation}} {{incode|Placement}}, dość łatwej do nauczenia.
FreeCAD oferuje szeroki wybór sposobów ustawiania tej właściwości, jeden jest bardziej dostosowany do drugiego w zależności od wiedzy i doświadczenia użytkownika, ale bardziej proste pisanie jest wyjaśnione w cytowanym samouczku, używa osobliwej definicji części {{incode|Rotation}} {{incode|Placement}}, dość łatwej do nauczenia.


{{Code|code=
{{Code|code=
FreeCAD.Placement(Vector(0, 0, 0), FreeCAD.Rotation(10, 20, 30), Vector(0, 0, 0))
FreeCAD.Placement(Vector(0, 0, 0), FreeCAD.Rotation(10, 20, 30), Vector(0, 0, 0))
}}
}}
Line 188: Line 189:
{| class="wikitable" border="1"
{| class="wikitable" border="1"
!Object!!Punkt odniesienia
!Object!!Punkt odniesienia
|-
|- align="left"
|Part.Box ||lewy ''(minx)'', przedni ''(miny)'', dolny ''(minz)'' wierzchołek
|Part.Box ||lewy ''(minx)'', przedni ''(miny)'', dolny ''(minz)'' wierzchołek
|-
|- align="left"
|Part.Sphere||środek kuli ''(tj. środek obwiedni)''
|Part.Sphere||środek kuli
|-
|- align="left"
|Part.Cylinder||środek dolnej powierzchni
|Part.Cylinder||środek dolnej powierzchni
|-
|- align="left"
|Part.Cone||środek dolnej powierzchni ''(lub wierzchołek, jeśli dolny promień wynosi 0)''
|Part.Cone||środek dolnej powierzchni ''(lub wierzchołek, jeśli dolny promień wynosi 0)''
|-
|- align="left"
|Part.Torus||środek torusa
|Part.Torus||środek torusa
|-
|- align="left"
|Cechy wywodzące się ze szkiców||cecha dziedziczy pozycję bazowego szkicu. Szkice zawsze zaczynają się od Pozycja = (0, 0, 0). Pozycja ta odpowiada punktowi położenia odniesienia.
|Cechy wywodzące się ze szkiców||cecha dziedziczy pozycję bazowego szkicu. Szkice zawsze zaczynają się od Pozycja = (0, 0, 0). Pozycja ta odpowiada punktowi położenia odniesienia.
|}
|}


Informacje te należy mieć na uwadze, zwłaszcza gdy musimy zastosować rotację.
Informacje te należy mieć na uwadze, zwłaszcza gdy musimy zastosować rotację.


Kilka przykładów może pomóc, usuń całą linię po metodzie {{incode|base_cyl}} i wstaw poniższy fragment kodu:
Kilka przykładów może pomóc, usuń całą linię po metodzie {{incode|my_cyl}} i wstaw poniższy fragment kodu:


{{Code|code=
{{Code|code=
def sfera(nome, rad):
def my_sphere(name, rad):
"""Create a Sphere."""
obj = DOC.addObject("Part::Sphere", nome)
obj = DOC.addObject("Part::Sphere", name)
obj.Radius = rad
obj.Radius = rad

DOC.recompute()
DOC.recompute()


return obj
return obj

def my_box2(name, len, wid, hei, cent=False, off_z=0):
"""Create a box with an optional z offset."""
obj_b = DOC.addObject("Part::Box", name)
obj_b.Length = len
obj_b.Width = wid
obj_b.Height = hei

if cent is True:
pos = Vector(len * -0.5, wid * -0.5, off_z)
else:
pos = Vector(0, 0, off_z)

obj_b.Placement = Placement(pos, ROT0, VEC0)

DOC.recompute()

return obj_b


def mfuse_obj(nome, objs):
def mfuse_obj(name, objs):
"""Fuse multiple objects."""
obj = DOC.addObject("Part::MultiFuse", nome)
obj = DOC.addObject("Part::MultiFuse", name)
obj.Shapes = objs
obj.Shapes = objs
obj.Refine = True
obj.Refine = True
Line 223: Line 244:
return obj
return obj


def aeroplano():
def airplane():
"""Create an airplane shaped solid."""
fuselage_length = 30
fuselage_diameter = 5
wing_span = fuselage_length * 1.75
wing_width = 7.5
wing_thickness = 1.5
tail_height = fuselage_diameter * 3.0
tail_position = fuselage_length * 0.70
tail_offset = tail_position - (wing_width * 0.5)


obj1 = my_cyl("main_body", 360, fuselage_diameter, fuselage_length)
lung_fus = 30
diam_fus = 5
ap_alare = lung_fus * 1.75
larg_ali = 7.5
spess_ali = 1.5
alt_imp = diam_fus * 3.0
pos_ali = (lung_fus*0.70)
off_ali = (pos_ali - (larg_ali * 0.5))


obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset)
obj1 = base_cyl('primo cilindro', 360, diam_fus, lung_fus)


obj3 = my_sphere("nose", fuselage_diameter)
obj2 = cubo('ali', ap_alare, spess_ali, larg_ali, True, off_ali)
obj3.Placement = Placement(Vector(0, 0, fuselage_length), ROT0, VEC0)


obj4 = my_box2("tail", wing_thickness, tail_height, wing_width, False, 0)
obj3 = sfera("naso", diam_fus)
obj3.Placement = FreeCAD.Placement(Vector(0, 0, lung_fus), FreeCAD.Rotation(0, 0, 0), Vector(0, 0, 0))
obj4.Placement = Placement(Vector(0, tail_height * -1, 0), ROT0, VEC0)

obj4 = cubo('impennaggio', spess_ali, alt_imp, larg_ali, False, 0)
obj4.Placement = FreeCAD.Placement(Vector(0, alt_imp * -1, 0), FreeCAD.Rotation(0, 0, 0), Vector(0, 0, 0))


objs = (obj1, obj2, obj3, obj4)
objs = (obj1, obj2, obj3, obj4)


obj = mfuse_obj("Forma esempio", objs)
obj = mfuse_obj("airplane", objs)
obj.Placement = FreeCAD.Placement(Vector(0, 0, 0), FreeCAD.Rotation(0, 0, -90), Vector(0, 0, pos_ali))
obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position))


DOC.recompute()
DOC.recompute()
Line 255: Line 276:
# objects definition
# objects definition


airplane()
aeroplano()


setview()
setview()

}}
}}


Wyjaśnijmy coś w kodzie:
Let's explain something in the code:


* Zastosowaliśmy metodę definiowania sfery, używając najprostszej definicji, używając tylko promienia.
* We have used a method to define a sphere, using the most easy definition, using only the radius.
* We have introduced a second writing for the '''Union''' or '''Fusion''', using multiple objects, not more distant from the usual '''Part::Fuse''' it uses '''Part:Multifuse'''. We only use one property {{incode|Shapes}}. We have passed a '''tuple''' as arguments, but it accepts also a '''list'''.
* Wprowadziliśmy drugi zapis dla '''Union''' lub '''Fusion''', używający wielu obiektów, nie bardziej odległy od zwykłego '''Part::Fuse''', który używa '''Part:Multifuse'''. Używamy tylko jednej właściwości {{incode|Shapes}}. Przekazaliśmy '''krotkę''' jako argumenty, ale akceptuje ona również '''listę'''.
* Zdefiniowaliśmy złożony obiekt '''airplane''', ale zrobiliśmy to w '''parametryczny''' sposób, definiując niektóre parametry i wyprowadzając inne parametry, poprzez pewne obliczenia, w oparciu o główne parametry.
* We have defined a complex object '''aeroplano''' (italian word for aeroplane), but we have done it in a '''"parametric"''' way, defining some parameters and deriving other parameters, through some calculation, based on the main parameters.
* We have used some Placement {{incode|Placement}} poperties around in the method and before returning the final geometries we have used a {{incode|Rotation}} property with the ''Yaw-Pitch-Roll'' writing. Note the last {{incode|Vector(0, 0, pos_ali)}}, that define a '''center of rotation''' of the whole geometry.
* Użyliśmy kilku właściwości {{incode|Umiejscowienie}} w metodzie, a przed zwróceniem ostatecznych geometrii użyliśmy właściwości {{incode|Obrót}} z napisem ''Przechylenie-Pochylenie-Odchylenie''. Zwróć uwagę na ostatni {{incode|Vector(0, 0, tail_position)}}, który definiuje '''środek obrotu''' całej geometrii.


{| class="wikitable"
{| class="wikitable"
|-
|-
| [[File:Aereo.png|thumb|left|aeroplane example]] || [[File:Aereo2.png|thumb|center|aereo rotated]]||
| [[File:Aereo.png|thumb|left|Przykładowy samolot]] || [[File:Aereo2.png|thumb|center|Samolot obrócony]]||
[[File:Aereo-prop.png|thumb|center|Prop Placement]]
[[File:Aereo-prop.png|thumb|center|Właściwość umiejscowienia]]
|}
|}


Można łatwo zauważyć, że geometria '''airplane''' obraca się wokół swojego "barycentrum" lub "środka ciężkości", który ustaliłem na środku skrzydła, miejscu, które jest stosunkowo "naturalne", ale można je umieścić gdziekolwiek chcesz.
It can be easily noted that '''aeroplano''' geometry rotate around his "barycenter" or "center of gravity", that I've fixed at wing center, a place that is relatively "natural", but could be placed wherever you want.


The first {{incode|Vector(0, 0, 0)}} is the Translation vector, not used here, but if you substitute {{incode|aeroplano()}} with these lines:
Pierwszy {{incode|Vector(0, 0, 0)}} jest wektorem translacji, nieużywanym tutaj, ale jeśli zastąpisz {{incode|airplane()}} tymi liniami:


{{Code|code=
{{Code|code=
obj_f = aeroplano()
obj_f = airplane()


print(obj_F.Placement)
print(obj_F.Placement)
}}
}}


W oknie raportu pojawi się ten tekst:
You will see in the Report window this text:


{{Code|code=
{{Code|code=
Line 289: Line 311:
}}
}}


Co się stało?
What has happened?


FreeCAD has translated the {{incode|Vector(0, 0, 0), FreeCAD.Rotation(0, 0, -90), Vector(0, 0, pos_ali)}} in other word our {{incode|Placement}} definition that specifies three components, '''Translation''', '''Rotation''' and ''center of rotation''' in the "internal" values of only two components, '''Translation''' and '''Rotation'''.
FreeCAD przemieścił {{incode|Vector(0, 0, 0), FreeCAD.Rotation(0, 0, -90), Vector(0, 0, tail_position)}} innymi słowy naszą definicję {{incode|Umiejscowienia}}, która określa trzy komponenty, '''Przemieszczenie''', '''Obrót''' i '''środek obrotu''' w "wewnętrznych" wartościach tylko dwóch komponentów, '''Przemieszczenie''' i '''Obrót'''.


you can easily visualize the value of {{incode|pos_ali}} using a print statement in the {{incode|aeroplano(...}} method and see that it is:
można łatwo zwizualizować wartość {{incode|tail_position}} za pomocą instrukcji print w metodzie {{incode|airplane()}} i zobaczyć, że tak jest:


{{Code|code=
{{Code|code=
pos ali = 21.0
tail_position = 21.0
}}
}}


in other word the '''rotation center''' of the geometry is at {{incode|Vector(0, 0, 21)}}, but this rotation center is not shown in the GUI, it could be entered as a {{incode|Placement}} value, it could not be easily retrieved.
Innymi słowy, ''środek obrotu'' geometrii znajduje się w {{Incode|Vector(0, 0, 21)}}, ale ten środek obrotu nie jest wyświetlany w GUI, można go wprowadzić jako wartość {{Incode|Umiejscowienie}}, nie można go łatwo wyszukać.


Jest to znaczenie słowa "niewygodny", którego użyłem do zdefiniowania właściwości {{incode|Umiejscowienie}}.
This is the meaning of the word "awkward" that I've used to define {{incode|Placement}} property.


To jest kompletny przykład kodu z przyzwoitym skryptem docstring zgodnie z konwencją [https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google Google docstrings]:

{{Code|code=
"""Sample code.

Filename:
airplane.py

Author:
Dormeletti Carlo (onekk)

Version:
1.0

License:
Creative Commons Attribution 3.0

Summary:
This code is a sample code written for FreeCAD Wiki page.
It create and airplane shaped solid made using standard "Part WB" built in shapes.

"""

import FreeCAD
from FreeCAD import Placement, Rotation, Vector

DOC = FreeCAD.activeDocument()
DOC_NAME = "Wiki_Example"

# Helpers methods

def clear_doc():
"""Clear activeDocument deleting all the objects."""
for obj in DOC.Objects:
DOC.removeObject(obj.Name)

def setview():
"""Rearrange View."""
FreeCAD.Gui.SendMsgToActiveView("ViewFit")
FreeCAD.Gui.activeDocument().activeView().viewAxometric()

if DOC is None:
FreeCAD.newDocument(DOC_NAME)
FreeCAD.setActiveDocument(DOC_NAME)
DOC = FreeCAD.activeDocument()
else:
clear_doc()

ROT0 = Rotation(0, 0, 0)
VEC0 = Vector(0, 0, 0)

# Script methods

def my_cyl(name, ang, rad, hei):
"""Create a Cylinder."""
obj = DOC.addObject("Part::Cylinder", name)
obj.Angle = ang
obj.Radius = rad
obj.Height = hei

DOC.recompute()

return obj

def my_sphere(name, rad):
"""Create a Sphere."""
obj = DOC.addObject("Part::Sphere", name)
obj.Radius = rad

DOC.recompute()

return obj

def my_box2(name, len, wid, hei, cent=False, off_z=0):
"""Create a box with an optional z offset."""
obj_b = DOC.addObject("Part::Box", name)
obj_b.Length = len
obj_b.Width = wid
obj_b.Height = hei

if cent is True:
pos = Vector(len * -0.5, wid * -0.5, off_z)
else:
pos = Vector(0, 0, off_z)

obj_b.Placement = Placement(pos, ROT0, VEC0)

DOC.recompute()

return obj_b

def mfuse_obj(name, objs):
"""Fuse multiple objects."""
obj = DOC.addObject("Part::MultiFuse", name)
obj.Shapes = objs
obj.Refine = True
DOC.recompute()

return obj

def airplane():
"""Create an airplane shaped solid."""
fuselage_length = 30
fuselage_diameter = 5
wing_span = fuselage_length * 1.75
wing_width = 7.5
wing_thickness = 1.5
tail_height = fuselage_diameter * 3.0
tail_position = fuselage_length * 0.70
tail_offset = tail_position - (wing_width * 0.5)

obj1 = my_cyl("main_body", 360, fuselage_diameter, fuselage_length)

obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset)

obj3 = my_sphere("nose", fuselage_diameter)
obj3.Placement = Placement(Vector(0, 0, fuselage_length), ROT0, VEC0)

obj4 = my_box2("tail", wing_thickness, tail_height, wing_width, False, 0)
obj4.Placement = Placement(Vector(0, tail_height * -1, 0), ROT0, VEC0)

objs = (obj1, obj2, obj3, obj4)

obj = mfuse_obj("airplane", objs)
obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position))

DOC.recompute()

return obj

# objects definition

airplane()

setview()
}}




{{Docnav
{{Docnav/pl
|[[Macros|Macros]]
|[[Macros/pl|Makrodefinicje]]
|[[Introduction_to_Python|Introduction to Python]]
|[[Introduction_to_Python/pl|Wprowadzenie do środowiska Python]]
}}
}}



Latest revision as of 09:33, 17 November 2023

Ćwiczenie
Temat
Tworzenie skryptów
Poziom trudności
Podstawowy
Czas wykonania
Autorzy
onekk Carlo
Wersja FreeCAD
0.19
Pliki z przykładami
Zobacz również
-

Wprowadzenie

Przez tworzenie skryptów rozumiemy tworzenie obiektów topologicznych za pomocą interpretera Python dla FreeCAD. Program FreeCAD może być używany jako "bardzo dobry" zamiennik OpenSCAD, głównie dlatego, że ma prawdziwy interpreter środowiska Python, co oznacza, że ma na pokładzie prawdziwy język programowania, prawie wszystko, co można zrobić z GUI, można zrobić za pomocą skryptu Python.

Niestety informacje na temat skryptów w dokumentacji, a nawet na tej Wiki, są rozproszone i brakuje im jednolitości "pisania”, a większość z nich jest wyjaśniona w zbyt techniczny sposób.

Rozpoczęcie pracy

Pierwszą przeszkodą w łatwej drodze do tworzenia skryptów jest to, że nie ma bezpośredniego sposobu na dostęp do wewnętrznego edytora Python FreeCAD poprzez pozycję menu lub ikonę na pasku narzędzi, ale wiedząc, że FreeCAD otwiera plik z rozszerzeniem .py w wewnętrznym edytorze Python, najprostszą sztuczką jest utworzenie go w ulubionym edytorze tekstu, a następnie otwarcie go za pomocą zwykłego polecenia Plik → Otwórz.

Aby zrobić to w uprzejmy sposób, plik musi być napisany w pewnym porządku, edytor FreeCAD Python ma dobre podświetlanie składni, którego brakuje w wielu prostych edytorach, takich jak Notatnik Windows lub niektóre podstawowe edytory Linuksa, więc wystarczy napisać te kilka linijek:

"""filename.py

   A short description of what the script does

"""

Zapisz je ze znaczącą nazwą z rozszerzeniem .py i załaduj wynikowy plik w FreeCAD, za pomocą wspomnianego polecenia Plik → Otwórz.

Minimalny przykład tego, co jest niezbędne w skrypcie, jest pokazany w tym fragmencie kodu, który można wykorzystać jako szablon dla prawie każdego przyszłego skryptu:

"""filename.py

   First FreeCAD Script

"""

import FreeCAD
from FreeCAD import Placement, Rotation, Vector

DOC = FreeCAD.activeDocument()
DOC_NAME = "Wiki_Example"

# Helpers methods

def clear_doc():
    """Clear activeDocument deleting all the objects."""
    for obj in DOC.Objects:
        DOC.removeObject(obj.Name)

def setview():
    """Rearrange View."""
    FreeCAD.Gui.SendMsgToActiveView("ViewFit")
    FreeCAD.Gui.activeDocument().activeView().viewAxometric()

if DOC is None:
    FreeCAD.newDocument(DOC_NAME)
    FreeCAD.setActiveDocument(DOC_NAME)
    DOC = FreeCAD.activeDocument()
else:
    clear_doc()

ROT0 = Rotation(0, 0, 0)
VEC0 = Vector(0, 0, 0)

Powyższy kod zawiera kilka sztuczek:

  • import FreeCAD Ta linia importuje FreeCAD w interpreterze FreeCAD Python, może wydawać się zbędna, ale tak nie jest.
  • from FreeCAD import Placement, Rotation, Vector. Umiejscowienie Obrót i Wektor są szeroko stosowane w skryptach FreeCAD, importowanie ich w ten sposób pozwoli zaoszczędzić na wywoływaniu ich za pomocą FreeCAD.Vector lub FreeCAD.Placement zamiast Vector lub Placement, zaoszczędzi to wiele naciśnięć klawiszy i sprawi, że linie kodu będą znacznie krótsze.

Zacznijmy od małego skryptu, który wykonuje bardzo małą pracę, ale pokazuje moc tej metody.

# Script methods

def my_box(name, len, wid, hei):
    """Create a box."""
    obj_b = DOC.addObject("Part::Box", name)
    obj_b.Length = len
    obj_b.Width = wid
    obj_b.Height = hei

    DOC.recompute()

    return obj_b

# objects definition

obj = my_box("test_cube", 5, 5, 5)

setview()

Wpisz powyższe linie kodu po # Script methods i naciśnij zieloną strzałkę na pasku narzędzi Makrodefinicje.

Zobaczysz kilka magicznych rzeczy, otworzy się nowy dokument o nazwie "Wiki_example", a w widoku 3D zobaczysz Sześcian, taki jak na poniższym obrazku.

Sześcian testowy.

Coś więcej

Nie jest to zbyt niesamowite? Tak, ale musimy od czegoś zacząć, możemy zrobić to samo z walcem, dodając te linie kodu po metodzie my_box() i przed linią: # objects definition.

def my_cyl(name, ang, rad, hei):
    """Create a Cylinder."""
    obj = DOC.addObject("Part::Cylinder", name)
    obj.Angle = ang
    obj.Radius = rad
    obj.Height = hei

    DOC.recompute()

    return obj

Nawet tutaj nie ma nic zbyt ekscytującego. Warto jednak zwrócić uwagę na kilka osobliwości:

  • Brak zwykłego odniesienia do App., obecnego w wielu fragmentach kodu Dokumentacji, jest zamierzony, kod ten może być użyty nawet do wywołania FreeCAD jako modułu w zewnętrznym interpreterze Pythona, nie jest to łatwe do zrobienia z AppImage, ale z pewną ostrożnością można to zrobić. Plus w standardowym motto Pythona, że "lepiej jawnie niż niejawnie" App. wyjaśnia w bardzo "kiepski" sposób, skąd pochodzą rzeczy.
  • Zwróć uwagę na użycie "stałej" nazwy przypisanej do aktywnego Dokumentu w DOC = FreeCAD. activeDocument(); activeDocument nie jest "stałą" w ścisłym sensie, ale w sposób "semantyczny" jest naszym "aktywnym dokumentem", który dla naszego użytku jest właściwą "stałą", więc konwencja Pythona polega na używaniu nazwy "ALL CAPS" dla "stałych", nie wspominając o tym, że DOC jest znacznie krótszy niż FreeCAD.activeDocument().
  • Każda metoda zwraca geometrię, będzie to jasne w dalszej części strony.
  • Geometria nie miała właściwości Placement, podczas używania prostych geometrii do tworzenia bardziej złożonych geometrii, zarządzanie Placement jest kłopotliwe.

Co teraz zrobić z tą geometrią?

Wprowadźmy operacje logiczne. Jako przykład początkowy umieść te linie po my_cyl, to utworzy metodę dla operacji Fusion znanej również jako Union:

def fuse_obj(name, obj_0, obj_1):
    """Fuse two objects."""
    obj = DOC.addObject("Part::Fuse", name)
    obj.Base = obj_0
    obj.Tool = obj_1
    obj.Refine = True
    DOC.recompute()

    return obj

Tutaj również nie ma nic wyjątkowego, należy jednak zwrócić uwagę na jednolitość kodowania metod; to podejście jest bardziej liniowe niż te spotykane w innych samouczkach dotyczących skryptów, ta "liniowość" znacznie pomaga w czytelności, a także w operacjach wycinania, kopiowania i wklejania.

Użyjmy geometrii, usuńmy linie poniżej sekcji kodu zaczynającej się od # objects definition i wstawmy następujące linie:

# objects definition

obj = my_box("test_cube", 5, 5, 5)

obj1 = my_cyl("test_cyl", 360, 2, 10)

fuse_obj("Fusion", obj, obj1)

setview()

Uruchom skrypt za pomocą zielonej strzałki, a w widoku 3D zobaczymy coś takiego:

Sześcian i cylinder.

Umiejscowienie

Koncepcja umiejscowienia jest stosunkowo złożona, zobacz poradnik samolotu, aby uzyskać bardziej dogłębne wyjaśnienie.

Zazwyczaj potrzebujemy umieścić geometrie względem siebie, podczas budowania złożonych obiektów jest to powtarzające się zadanie, najczęstszym sposobem jest użycie właściwości geometrii Placement.

FreeCAD oferuje szeroki wybór sposobów ustawiania tej właściwości, jeden jest bardziej dostosowany do drugiego w zależności od wiedzy i doświadczenia użytkownika, ale bardziej proste pisanie jest wyjaśnione w cytowanym samouczku, używa osobliwej definicji części Rotation Placement, dość łatwej do nauczenia.

FreeCAD.Placement(Vector(0, 0, 0), FreeCAD.Rotation(10, 20, 30), Vector(0, 0, 0))

Ale ponad innymi rozważaniami, jedna rzecz jest kluczowa, geometria punkt odniesienia. Innymi słowy punkt, z którego obiekt jest modelowany przez FreeCAD, jak opisano w tej tabeli, skopiowanej z umiejscowienia:

Object Punkt odniesienia
Part.Box lewy (minx), przedni (miny), dolny (minz) wierzchołek
Part.Sphere środek kuli
Part.Cylinder środek dolnej powierzchni
Part.Cone środek dolnej powierzchni (lub wierzchołek, jeśli dolny promień wynosi 0)
Part.Torus środek torusa
Cechy wywodzące się ze szkiców cecha dziedziczy pozycję bazowego szkicu. Szkice zawsze zaczynają się od Pozycja = (0, 0, 0). Pozycja ta odpowiada punktowi położenia odniesienia.

Informacje te należy mieć na uwadze, zwłaszcza gdy musimy zastosować rotację.

Kilka przykładów może pomóc, usuń całą linię po metodzie my_cyl i wstaw poniższy fragment kodu:

def my_sphere(name, rad):
    """Create a Sphere."""
    obj = DOC.addObject("Part::Sphere", name)
    obj.Radius = rad

    DOC.recompute()

    return obj

def my_box2(name, len, wid, hei, cent=False, off_z=0):
    """Create a box with an optional z offset."""
    obj_b = DOC.addObject("Part::Box", name)
    obj_b.Length = len
    obj_b.Width = wid
    obj_b.Height = hei

    if cent is True:
        pos = Vector(len * -0.5, wid * -0.5, off_z)
    else:
        pos = Vector(0, 0, off_z)

    obj_b.Placement = Placement(pos, ROT0, VEC0)

    DOC.recompute()

    return obj_b

def mfuse_obj(name, objs):
    """Fuse multiple objects."""
    obj = DOC.addObject("Part::MultiFuse", name)
    obj.Shapes = objs
    obj.Refine = True
    DOC.recompute()

    return obj

def airplane():
    """Create an airplane shaped solid."""
    fuselage_length = 30
    fuselage_diameter = 5
    wing_span = fuselage_length * 1.75
    wing_width = 7.5
    wing_thickness = 1.5
    tail_height = fuselage_diameter * 3.0
    tail_position = fuselage_length * 0.70
    tail_offset = tail_position - (wing_width * 0.5)

    obj1 = my_cyl("main_body", 360, fuselage_diameter, fuselage_length)

    obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset)

    obj3 = my_sphere("nose", fuselage_diameter)
    obj3.Placement = Placement(Vector(0, 0, fuselage_length), ROT0, VEC0)

    obj4 = my_box2("tail", wing_thickness, tail_height, wing_width, False, 0)
    obj4.Placement = Placement(Vector(0, tail_height * -1, 0), ROT0, VEC0)

    objs = (obj1, obj2, obj3, obj4)

    obj = mfuse_obj("airplane", objs)
    obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position))

    DOC.recompute()

    return obj

# objects definition

airplane()

setview()

Wyjaśnijmy coś w kodzie:

  • Zastosowaliśmy metodę definiowania sfery, używając najprostszej definicji, używając tylko promienia.
  • Wprowadziliśmy drugi zapis dla Union lub Fusion, używający wielu obiektów, nie bardziej odległy od zwykłego Part::Fuse, który używa Part:Multifuse. Używamy tylko jednej właściwości Shapes. Przekazaliśmy krotkę jako argumenty, ale akceptuje ona również listę.
  • Zdefiniowaliśmy złożony obiekt airplane, ale zrobiliśmy to w parametryczny sposób, definiując niektóre parametry i wyprowadzając inne parametry, poprzez pewne obliczenia, w oparciu o główne parametry.
  • Użyliśmy kilku właściwości Umiejscowienie w metodzie, a przed zwróceniem ostatecznych geometrii użyliśmy właściwości Obrót z napisem Przechylenie-Pochylenie-Odchylenie. Zwróć uwagę na ostatni Vector(0, 0, tail_position), który definiuje środek obrotu całej geometrii.
Przykładowy samolot
Samolot obrócony
Właściwość umiejscowienia

Można łatwo zauważyć, że geometria airplane obraca się wokół swojego "barycentrum" lub "środka ciężkości", który ustaliłem na środku skrzydła, miejscu, które jest stosunkowo "naturalne", ale można je umieścić gdziekolwiek chcesz.

Pierwszy Vector(0, 0, 0) jest wektorem translacji, nieużywanym tutaj, ale jeśli zastąpisz airplane() tymi liniami:

obj_f = airplane()

print(obj_F.Placement)

W oknie raportu pojawi się ten tekst:

Placement [Pos=(0, -21, 21), Yaw-Pitch-Roll=(0, 0, -90)]

Co się stało?

FreeCAD przemieścił Vector(0, 0, 0), FreeCAD.Rotation(0, 0, -90), Vector(0, 0, tail_position) innymi słowy naszą definicję Umiejscowienia, która określa trzy komponenty, Przemieszczenie, Obrót i środek obrotu w "wewnętrznych" wartościach tylko dwóch komponentów, Przemieszczenie i Obrót.

można łatwo zwizualizować wartość tail_position za pomocą instrukcji print w metodzie airplane() i zobaczyć, że tak jest:

tail_position = 21.0

Innymi słowy, środek obrotu geometrii znajduje się w Vector(0, 0, 21), ale ten środek obrotu nie jest wyświetlany w GUI, można go wprowadzić jako wartość Umiejscowienie, nie można go łatwo wyszukać.

Jest to znaczenie słowa "niewygodny", którego użyłem do zdefiniowania właściwości Umiejscowienie.


To jest kompletny przykład kodu z przyzwoitym skryptem docstring zgodnie z konwencją Google docstrings:

"""Sample code.

Filename:
   airplane.py

Author:
    Dormeletti Carlo (onekk)

Version:
    1.0

License:
    Creative Commons Attribution 3.0

Summary:
    This code is a sample code written for FreeCAD Wiki page.
    It create and airplane shaped solid made using standard "Part WB" built in shapes.

"""

import FreeCAD
from FreeCAD import Placement, Rotation, Vector

DOC = FreeCAD.activeDocument()
DOC_NAME = "Wiki_Example"

# Helpers methods

def clear_doc():
    """Clear activeDocument deleting all the objects."""
    for obj in DOC.Objects:
        DOC.removeObject(obj.Name)

def setview():
    """Rearrange View."""
    FreeCAD.Gui.SendMsgToActiveView("ViewFit")
    FreeCAD.Gui.activeDocument().activeView().viewAxometric()

if DOC is None:
    FreeCAD.newDocument(DOC_NAME)
    FreeCAD.setActiveDocument(DOC_NAME)
    DOC = FreeCAD.activeDocument()
else:
    clear_doc()

ROT0 = Rotation(0, 0, 0)
VEC0 = Vector(0, 0, 0)

# Script methods

def my_cyl(name, ang, rad, hei):
    """Create a Cylinder."""
    obj = DOC.addObject("Part::Cylinder", name)
    obj.Angle = ang
    obj.Radius = rad
    obj.Height = hei

    DOC.recompute()

    return obj

def my_sphere(name, rad):
    """Create a Sphere."""
    obj = DOC.addObject("Part::Sphere", name)
    obj.Radius = rad

    DOC.recompute()

    return obj

def my_box2(name, len, wid, hei, cent=False, off_z=0):
    """Create a box with an optional z offset."""
    obj_b = DOC.addObject("Part::Box", name)
    obj_b.Length = len
    obj_b.Width = wid
    obj_b.Height = hei

    if cent is True:
        pos = Vector(len * -0.5, wid * -0.5, off_z)
    else:
        pos = Vector(0, 0, off_z)

    obj_b.Placement = Placement(pos, ROT0, VEC0)

    DOC.recompute()

    return obj_b

def mfuse_obj(name, objs):
    """Fuse multiple objects."""
    obj = DOC.addObject("Part::MultiFuse", name)
    obj.Shapes = objs
    obj.Refine = True
    DOC.recompute()

    return obj

def airplane():
    """Create an airplane shaped solid."""
    fuselage_length = 30
    fuselage_diameter = 5
    wing_span = fuselage_length * 1.75
    wing_width = 7.5
    wing_thickness = 1.5
    tail_height = fuselage_diameter * 3.0
    tail_position = fuselage_length * 0.70
    tail_offset = tail_position - (wing_width * 0.5)

    obj1 = my_cyl("main_body", 360, fuselage_diameter, fuselage_length)

    obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset)

    obj3 = my_sphere("nose", fuselage_diameter)
    obj3.Placement = Placement(Vector(0, 0, fuselage_length), ROT0, VEC0)

    obj4 = my_box2("tail", wing_thickness, tail_height, wing_width, False, 0)
    obj4.Placement = Placement(Vector(0, tail_height * -1, 0), ROT0, VEC0)

    objs = (obj1, obj2, obj3, obj4)

    obj = mfuse_obj("airplane", objs)
    obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position))

    DOC.recompute()

    return obj

# objects definition

airplane()

setview()