Documented the image generation module

colorcode/imgen/draw.py

 
+"""
+Image generation
+
+This module is tasked with generating images
+from the code matrices created by code builder modules.
+"""
+
 from PIL import Image
 
 def _sumtuple(*t):
@@ -8,42 +15,155 @@ def _sumtuple(*t):
 		return sum(t)
 
 class ImGenerator(object):
+	"""
+	Image generator
 
-	def __init__(self, data, interpolation, imageMode, modSize, quietZone = 1):
-		self.interpolation = interpolation.value
+	This class turns the code matrices into one single image
+	containing the interleaved codes.
+
+	Parameters
+	----------
+	data
+		A list or tuple containing the code matrices as Numpy arrays
+	interleaving
+		The interleaving enum element corresponding to the interleaving
+		that will be used when generating the image
+	imageMode
+		The Pillow image mode, as a string
+	modSize
+		The side size, in pixels, of a single module.
+		The total size of the image is ``(code size + quiet zone size) * module size``
+	quietZone
+		The size, in number of modules, of the quiet zone surrounding the code.
+		A quiet zone is a blank area surrounding the code for easier scanning.
+	
+	Attributes
+	----------
+	interleaving
+		The actual interleaving list, *not* the enum item
+	qzColor
+		The color value of the quiet zone
+	dataSize
+		The side size of the data area, in number of modules
+	imageSize
+		The size tuple passed to Pillow to create the image.
+		Contains ``(width, height)`` expressed in pixels
+	image
+		The actual Pillow image object
+	"""
+	def __init__(self, data, interleaving, imageMode, modSize, quietZone = 1):
+		self.interleaving = interleaving.value
 		self.data = data
 		self.quietZone = quietZone
-		self.qzColor = _sumtuple(*(i[0] for i in self.interpolation))
+		self.qzColor = _sumtuple(*(i[0] for i in self.interleaving))
 		self.dataSize = data[0].shape[0]
 		self.modSize = modSize
 		self.imageSize = (modSize * (quietZone * 2 + self.dataSize),) * 2
 		self.image = Image.new(imageMode, self.imageSize)
 
 	def moduleColor(self, modX, modY):
+		"""
+		Color of a module at given position
+
+		Module position is index starting at 0 at the upper-left corner
+		of the quiet zone. X increases from left to right, Y increases
+		from top to bottom.
+
+		This method is the one that processes the interleaving.
+
+		Parameters
+		----------
+		modX : int
+			X-coordinate of the module
+		modY : int
+			Y-coordinate of the module
+		
+		Returns
+		-------
+		tuple or int
+			The color value to be passed to Pillow when setting the color of the module.
+			Uses the color defined in the selected interleaving.
+		"""
 		if modX not in range(self.quietZone, self.quietZone + self.dataSize):
 			return self.qzColor
 		if modY not in range(self.quietZone, self.quietZone + self.dataSize):
 			return self.qzColor
-		return _sumtuple(*(self.interpolation[i][1 if data[modY - self.quietZone, modX - self.quietZone] else 0] for i, data in enumerate(self.data)))
+		return _sumtuple(*(self.interleaving[i][1 if data[modY - self.quietZone, modX - self.quietZone] else 0] for i, data in enumerate(self.data)))
 
 	def moduleCoordinates(self, modX, modY):
+		"""
+		Pixel coordinates of a full module
+
+		Helper generator that yields the ``(X, Y)`` coordinate tuples
+		for all pixels contained in a single module
+
+		Parameters
+		----------
+		modX : int
+			X-coordinate of the module
+		modY : int
+			Y-coordinate of the module
+		"""
 		for i in range(self.modSize):
 			for j in range(self.modSize):
 				yield (j + modX * self.modSize, i + modY * self.modSize)
 
 	def moduleRect(self, modX, modY):
+		"""
+		Rectangle area of a module
+
+		Returns the rectangle definition to be passed to Pillow
+		in order to draw a single module in a call to ``ImageDraw.rectangle``
+
+		Parameters
+		----------
+		modX : int
+			X-coordinate of the module
+		modY : int
+			Y-coordinate of the module
+		"""
 		return [modX * self.modSize, modY * self.modSize, (modX + 1) * self.modSize, (modY + 1) * self.modSize,]
 
 	def drawModule(self, modX, modY):
+		"""
+		Draws a given module
+
+		This method sets the color of an entire module
+		to the one determined by the codes values and the interleaving.
+
+		Parameters
+		----------
+		modX : int
+			X-coordinate of the module
+		modY : int
+			Y-coordinate of the module
+		"""
 		color = self.moduleColor(modX, modY)
 		for coords in self.moduleCoordinates(modX, modY):
 			self.image.putpixel(coords, color)
 
 	def drawCode(self):
+		"""
+		Draws the entire code
+
+		This method merely calls `drawModule`for every module coordinate in the image.
+		"""
 		size = self.quietZone * 2 + self.dataSize
 		for y in range(size):
 			for x in range(size):
 				self.drawModule(x, y)
 	
 	def saveImage(self, fname, *args, **kwargs):
+		"""
+		Saves the image to a file
+
+		This method passes its arguments to ``Image.save``
+		in order to save the image to disk.
+		Refer to Pillow documentation for more informations.
+
+		Parameters
+		----------
+		fname
+			The file path, or already open file object or file descriptor
+		"""
 		self.image.save(fname, *args, **kwargs)