From: daid Date: Fri, 14 Feb 2014 09:17:34 +0000 (+0100) Subject: More documentation. X-Git-Tag: 14.02-RC2~14 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=b948879ac78129883786173051def8ed4f98f6f8;p=cura.git More documentation. --- diff --git a/Cura/serialCommunication.py b/Cura/serialCommunication.py index 7a2d91ea..7447f83a 100644 --- a/Cura/serialCommunication.py +++ b/Cura/serialCommunication.py @@ -15,6 +15,10 @@ import json from Cura.util import machineCom class serialComm(object): + """ + The serialComm class is the interface class which handles the communication between stdin/stdout and the machineCom class. + This interface class is used to run the (USB) serial communication in a different process then the GUI. + """ def __init__(self, portName): self._comm = None self._gcodeList = [] diff --git a/Cura/util/gcodeGenerator.py b/Cura/util/gcodeGenerator.py index cb6ed709..47b473c4 100644 --- a/Cura/util/gcodeGenerator.py +++ b/Cura/util/gcodeGenerator.py @@ -9,6 +9,10 @@ import math from Cura.util import profile class gcodeGenerator(object): + """ + Generates a simple set of GCode commands for RepRap GCode firmware. + Use the add* commands to build the GCode, and then use the list function to retrieve the resulting gcode. + """ def __init__(self): self._feedPrint = profile.getProfileSettingFloat('print_speed') * 60 self._feedTravel = profile.getProfileSettingFloat('travel_speed') * 60 diff --git a/Cura/util/gcodeInterpreter.py b/Cura/util/gcodeInterpreter.py index 4bf13a7a..45f65c0f 100644 --- a/Cura/util/gcodeInterpreter.py +++ b/Cura/util/gcodeInterpreter.py @@ -15,6 +15,9 @@ import cStringIO as StringIO from Cura.util import profile def gcodePath(newType, pathType, layerThickness, startPoint): + """ + Build a gcodePath object. This used to be objects, however, this code is timing sensitive and dictionaries proved to be faster. + """ return {'type': newType, 'pathType': pathType, 'layerThickness': layerThickness, @@ -22,6 +25,10 @@ def gcodePath(newType, pathType, layerThickness, startPoint): 'extrusion': [0.0]} class gcode(object): + """ + The heavy lifting GCode parser. This is most likely the hardest working python code in Cura. + It parses a GCode file and stores the result in layers where each layer as paths that describe the GCode. + """ def __init__(self): self.regMatch = {} self.layerList = None diff --git a/Cura/util/machineCom.py b/Cura/util/machineCom.py index dc3430b4..b0cac8bb 100644 --- a/Cura/util/machineCom.py +++ b/Cura/util/machineCom.py @@ -1,6 +1,6 @@ """ -MachineCom handles communication with GCode based printers trough serial ports. -For actual printing of objects this module is used from Cura.serialCommunication and ran in a seperate process. +MachineCom handles communication with GCode based printers trough (USB) serial ports. +For actual printing of objects this module is used from Cura.serialCommunication and ran in a separate process. """ __copyright__ = "Copyright (C) 2013 David Braam - Released under terms of the AGPLv3 License" @@ -29,6 +29,11 @@ except: pass def serialList(forAutoDetect=False): + """ + Retrieve a list of serial ports found in the system. + :param forAutoDetect: if true then only the USB serial ports are listed. Else all ports are listed. + :return: A list of strings where each string is a serial port. + """ baselist=[] if platform.system() == "Windows": try: @@ -54,18 +59,11 @@ def serialList(forAutoDetect=False): baselist.append('VIRTUAL') return baselist -def machineIsConnected(): - #UltiGCode is designed for SD-Card printing, so never auto-detect the serial port. - port = profile.getMachineSetting('serial_port') - if port == 'AUTO': - if profile.getMachineSetting('gcode_flavor') == 'UltiGCode': - return False - return len(serialList(True)) > 0 - if platform.system() == "Windows": - return port in serialList() - return os.path.isfile(port) - def baudrateList(): + """ + :return: a list of integers containing all possible baudrates at which we can communicate. + Used for auto-baudrate detection as well as manual baudrate selection. + """ ret = [250000, 230400, 115200, 57600, 38400, 19200, 9600] if profile.getMachineSetting('serial_baud_auto') != '': prev = int(profile.getMachineSetting('serial_baud_auto')) @@ -75,6 +73,10 @@ def baudrateList(): return ret class VirtualPrinter(): + """ + A virtual printer class used for debugging. Acts as a serial.Serial class, but without connecting to any port. + Only available when running the development version of Cura. + """ def __init__(self): self.readList = ['start\n', 'Marlin: Virtual Marlin!\n', '\x80\n'] self.temp = 0.0 @@ -127,6 +129,10 @@ class VirtualPrinter(): self.readList = None class MachineComPrintCallback(object): + """ + Base class for callbacks from the MachineCom class. + This class has all empty implementations and is attached to the MachineCom if no other callback object is attached. + """ def mcLog(self, message): pass @@ -146,6 +152,10 @@ class MachineComPrintCallback(object): pass class MachineCom(object): + """ + Class for (USB) serial communication with 3D printers. + This class keeps track of if the connection is still live, can auto-detect serial ports and baudrates. + """ STATE_NONE = 0 STATE_OPEN_SERIAL = 1 STATE_DETECT_SERIAL = 2 diff --git a/Cura/util/meshLoaders/dae.py b/Cura/util/meshLoaders/dae.py index 9dd0e91b..428a8300 100644 --- a/Cura/util/meshLoaders/dae.py +++ b/Cura/util/meshLoaders/dae.py @@ -17,6 +17,12 @@ def loadScene(filename): return [loader.obj] class daeLoader(object): + """ + COLLADA object loader. This class is a bit of a mess, COLLADA files are complex beasts, and this code has only been tweaked to accept + the COLLADA files exported from SketchUp. + + Parts of this class can be cleaned up and improved by using more numpy. + """ def __init__(self, filename): self.obj = printableObject.printableObject(filename) self.mesh = self.obj._addMesh() diff --git a/Cura/util/objectScene.py b/Cura/util/objectScene.py index 01b535ee..1a3437c8 100644 --- a/Cura/util/objectScene.py +++ b/Cura/util/objectScene.py @@ -12,11 +12,21 @@ from Cura.util import profile from Cura.util import polygon class _objectOrder(object): + """ + Internal object used by the _objectOrderFinder to keep track of a possible order in which to print objects. + """ def __init__(self, order, todo): + """ + :param order: List of indexes in which to print objects, ordered by printing order. + :param todo: List of indexes which are not yet inserted into the order list. + """ self.order = order self.todo = todo class _objectOrderFinder(object): + """ + Internal object used by the Scene class to figure out in which order to print objects. + """ def __init__(self, scene, leftToRight, frontToBack, gantryHeight): self._scene = scene self._objs = scene.objects() @@ -91,6 +101,10 @@ class _objectOrderFinder(object): return polygon.polygonCollision(obj._boundaryHull + obj.getPosition(), addObj._headAreaHull + addObj.getPosition()) class Scene(object): + """ + The scene class keep track of an collection of objects on a build platform and their state. + It can figure out in which order to print them (if any) and if an object can be printed at all. + """ def __init__(self): self._objectList = [] self._sizeOffsets = numpy.array([0.0,0.0], numpy.float32) diff --git a/Cura/util/pluginInfo.py b/Cura/util/pluginInfo.py index 0d71e136..7290c8bc 100644 --- a/Cura/util/pluginInfo.py +++ b/Cura/util/pluginInfo.py @@ -18,6 +18,10 @@ from Cura.util import resources _pluginList = None class pluginInfo(object): + """ + Plugin information object. Used to keep track of information about the available plugins in this installation of Cura. + Each plugin as meta-data associated with it which can be retrieved from this class. + """ def __init__(self, dirname, filename): self._dirname = dirname self._filename = filename diff --git a/Cura/util/printableObject.py b/Cura/util/printableObject.py index ff980aae..ce761325 100644 --- a/Cura/util/printableObject.py +++ b/Cura/util/printableObject.py @@ -15,6 +15,13 @@ numpy.seterr(all='ignore') from Cura.util import polygon class printableObject(object): + """ + A printable object is an object that can be printed and is on the build platform. + It contains 1 or more Meshes. Where more meshes are used for multi-extrusion. + + Each object has a 3x3 transformation matrix to rotate/scale the object. + This object also keeps track of the 2D boundary polygon used for object collision in the objectScene class. + """ def __init__(self, originFilename): self._originFilename = originFilename if originFilename is None: @@ -290,6 +297,11 @@ class printableObject(object): return numpy.array(vertexList, numpy.float32), meshList class mesh(object): + """ + A mesh is a list of 3D triangles build from vertexes. Each triangle has 3 vertexes. + + A "VBO" can be associated with this object, which is used for rendering this object. + """ def __init__(self, obj): self.vertexes = None self.vertexCount = 0 diff --git a/Cura/util/printerConnection/doodle3dConnect.py b/Cura/util/printerConnection/doodle3dConnect.py index 9c309ee5..ec2f5534 100644 --- a/Cura/util/printerConnection/doodle3dConnect.py +++ b/Cura/util/printerConnection/doodle3dConnect.py @@ -13,6 +13,10 @@ import time from Cura.util.printerConnection import printerConnectionBase class doodle3dConnectionGroup(printerConnectionBase.printerConnectionGroup): + """ + The Doodle3D connection group runs a thread to poll for Doodle3D boxes. + For each Doodle3D box it finds, it creates a Doodle3DConnect object. + """ PRINTER_LIST_HOST = 'connect.doodle3d.com' PRINTER_LIST_PATH = '/api/list.php' @@ -93,9 +97,11 @@ class doodle3dConnectionGroup(printerConnectionBase.printerConnectionGroup): return response -#Class to connect and print files with the doodle3d.com wifi box -# Auto-detects if the Doodle3D box is available with a printer class doodle3dConnect(printerConnectionBase.printerConnectionBase): + """ + Class to connect and print files with the doodle3d.com wifi box + Auto-detects if the Doodle3D box is available with a printer and handles communication with the Doodle3D API + """ def __init__(self, host, name, group): super(doodle3dConnect, self).__init__(name) diff --git a/Cura/util/printerConnection/dummyConnection.py b/Cura/util/printerConnection/dummyConnection.py index 943cc499..17bebcdc 100644 --- a/Cura/util/printerConnection/dummyConnection.py +++ b/Cura/util/printerConnection/dummyConnection.py @@ -13,6 +13,10 @@ import time from Cura.util.printerConnection import printerConnectionBase class dummyConnectionGroup(printerConnectionBase.printerConnectionGroup): + """ + Group used for dummy conections. Always shows 2 dummy connections for debugging. + Has a very low priority so it does not prevent other connections from taking priority. + """ def __init__(self): super(dummyConnectionGroup, self).__init__("Dummy") self._list = [dummyConnection("Dummy 1"), dummyConnection("Dummy 2")] @@ -26,8 +30,10 @@ class dummyConnectionGroup(printerConnectionBase.printerConnectionGroup): def getPriority(self): return -100 -#Dummy printer class which is always class dummyConnection(printerConnectionBase.printerConnectionBase): + """ + A dummy printer class to debug printer windows. + """ def __init__(self, name): super(dummyConnection, self).__init__(name) diff --git a/Cura/util/printerConnection/printerConnectionManager.py b/Cura/util/printerConnection/printerConnectionManager.py index 2322742c..9fde1cbe 100644 --- a/Cura/util/printerConnection/printerConnectionManager.py +++ b/Cura/util/printerConnection/printerConnectionManager.py @@ -14,6 +14,10 @@ from Cura.util.printerConnection import serialConnection from Cura.util.printerConnection import doodle3dConnect class PrinterConnectionManager(object): + """ + The printer connection manager has one of each printer connection groups. Sorted on priority. + It can retrieve the first available connection as well as all available connections. + """ def __init__(self): self._groupList = [] if version.isDevVersion(): diff --git a/Cura/util/profile.py b/Cura/util/profile.py index db538149..f563d6dc 100644 --- a/Cura/util/profile.py +++ b/Cura/util/profile.py @@ -39,15 +39,17 @@ settingsList = [] _selectedMachineIndex = 0 class setting(object): - #A setting object contains a configuration setting. These are globally accessible trough the quick access functions - # and trough the settingsDictionary function. - # Settings can be: - # * profile settings (settings that effect the slicing process and the print result) - # * preferences (settings that effect how cura works and acts) - # * machine settings (settings that relate to the physical configuration of your machine) - # * alterations (bad name copied from Skeinforge. These are the start/end code pieces) - # Settings have validators that check if the value is valid, but do not prevent invalid values! - # Settings have conditions that enable/disable this setting depending on other settings. (Ex: Dual-extrusion) + """ + A setting object contains a configuration setting. These are globally accessible trough the quick access functions + and trough the settingsDictionary function. + Settings can be: + * profile settings (settings that effect the slicing process and the print result) + * preferences (settings that effect how cura works and acts) + * machine settings (settings that relate to the physical configuration of your machine) + * alterations (bad name copied from Skeinforge. These are the start/end code pieces) + Settings have validators that check if the value is valid, but do not prevent invalid values! + Settings have conditions that enable/disable this setting depending on other settings. (Ex: Dual-extrusion) + """ def __init__(self, name, default, type, category, subcategory): self._name = name self._label = name diff --git a/Cura/util/sliceEngine.py b/Cura/util/sliceEngine.py index d820b6fb..87b3e4e2 100644 --- a/Cura/util/sliceEngine.py +++ b/Cura/util/sliceEngine.py @@ -26,6 +26,10 @@ from Cura.util import version from Cura.util import gcodeInterpreter def getEngineFilename(): + """ + Finds and returns the path to the current engine executable. This is OS depended. + :return: The full path to the engine executable. + """ if platform.system() == 'Windows': if version.isDevVersion() and os.path.exists('C:/Software/Cura_SteamEngine/_bin/Release/Cura_SteamEngine.exe'): return 'C:/Software/Cura_SteamEngine/_bin/Release/Cura_SteamEngine.exe' @@ -38,13 +42,11 @@ def getEngineFilename(): return '/usr/local/bin/CuraEngine' return os.path.abspath(os.path.join(os.path.dirname(__file__), '../..', 'CuraEngine')) -def getTempFilename(): - warnings.simplefilter('ignore') - ret = os.tempnam(None, "Cura_Tmp") - warnings.simplefilter('default') - return ret - class EngineResult(object): + """ + Result from running the CuraEngine. + Contains the engine log, polygons retrieved from the engine, the GCode and some meta-data. + """ def __init__(self): self._engineLog = [] self._gcodeData = StringIO.StringIO() @@ -156,6 +158,11 @@ class EngineResult(object): pass class Engine(object): + """ + Class used to communicate with the CuraEngine. + The CuraEngine is ran as a 2nd process and reports back information trough stderr. + GCode trough stdout and has a socket connection for polygon information and loading the 3D model into the engine. + """ GUI_CMD_REQUEST_MESH = 0x01 GUI_CMD_SEND_POLYGONS = 0x02 diff --git a/Cura/util/youmagine.py b/Cura/util/youmagine.py index 6e0615c6..5aa6710a 100644 --- a/Cura/util/youmagine.py +++ b/Cura/util/youmagine.py @@ -9,6 +9,10 @@ import httplib as httpclient import urllib class httpUploadDataStream(object): + """ + For http uploads we need a readable/writable datasteam to use with the httpclient.HTTPSConnection class. + This is used to facilitate file uploads towards Youmagine. + """ def __init__(self, progressCallback): self._dataList = [] self._totalLength = 0 @@ -38,6 +42,10 @@ class httpUploadDataStream(object): return self._totalLength class Youmagine(object): + """ + Youmagine connection object. Has various functions to communicate with Youmagine. + These functions are blocking and thus this class should be used from a thread. + """ def __init__(self, authToken, progressCallback = None): self._hostUrl = 'api.youmagine.com' self._viewUrl = 'www.youmagine.com' @@ -197,8 +205,11 @@ class Youmagine(object): return {'error': error} -#Fake Youmagine class to test without internet class FakeYoumagine(Youmagine): + """ + Fake Youmagine class to test without internet, acts the same as the YouMagine class, but without going to the internet. + Assists in testing UI features. + """ def __init__(self, authToken, callback): super(FakeYoumagine, self).__init__(authToken) self._authUrl = 'file:///C:/Models/output.html'