# Reading slice elements from an RP3-generated text file.
# Last edited on 2021-06-04 14:52:43 by jstolfi

import txt_read_IMP

def read(rd, mp_cont, mp_fill, angle, shift):
  # Reads from the file handle {rd} a description of the contours, 
  # raster filling elements, contacts, and link paths of a single object slice
  # with a simple raster-type solid fill.
  #
  # Returns (1) a list {OCRS} of contour paths, (2) a list {OPHS} of
  # {Path} objects that are the filling elements, and (3) a list {CTS}
  # of contacts between the traces of the filling paths. Also returns
  # (4) the {Z} coordinate of the slice.  
  #
  # All points in the file will be rotated by {-angle} radians about the
  # origin, and then translated by the vector {shift} (a pair of
  # {float}s). Note that rotation may change the sign of some
  # coordnates. A suitable {shift} can be used to ensure that all
  # coordinates in the resulting paths and contacts are non-negative.
  # 
  # ??? Describe the file format ???
  #
  # The contour elements (defined by the lines with 'C' code) are closed
  # paths, properly oriented, with trace parameters {m_cont}. The
  # procedure {path.compute_contour_nesting} is called to compute and
  # save their nesting relations.
  # 
  # The filling elements must be parallel raster traces whose axis makes
  # the specified {angle} (in radians, counterclockwise) with the
  # horizontal.
  #
  # Each filling element ('R' code) is converted to a single {Move}
  # object with parameters {mp_fill} and then to a single-move {Path}
  # object. The order of the rasters in the {OPHS} list is the same as
  # that in the file. The orientation of the latter in {OPHS} is the one
  # indicated in the file by the 'rbit' field of its 'R' line.
  # 
  # The procedure saves in each path of {OPHS} the 'group' index from
  # the respective 'R' line, with {path_hp.set_group}. This index is
  # supposed to indicate a user-given grouping of rasters into blocks
  # such as the continuour raster sequence (OCRS) created by RP3.
  # 
  # The lines with 'L' code are converted to contacts and link paths
  # between the filling elements. Each link path will consist of one or
  # more traces with the same parameters {mp_fill}. These links are
  # attached to the raster paths with {path_hp.add_link} so that they
  # can be obtained with {path_hp.get_links} and
  # {path_hp.connecting_link}.
  #
  # Each contact is also attached to the two adjacent paths {oph0,oph1}
  # with {path_hp.add_contact(oph0,0)} and
  # {path_hp.add_contact(oph1,1)}, assuming that {oph0} is lower than
  # {oph1} in the direction at 90 degrees ccw from {angle}.
  # 
  return txt_read_IMP.read(rd, mp_cont, mp_fill, angle)