# Tools for raster fillings.
# Last edited on 2021-06-01 15:31:32 by jstolfi

import raster_IMP
import path

# A /raster fill element/ is a path consisting of a single move which is
# a trace. A /raster filling/ is a collection of raster fill elements of
# the same width {wd} that are all parallel to some direction {xdir},
# and whose positions along the perpendicular direction {ydir} are all
# approximately integer multiples of {wd} plus some arbitrary shift, the
# /scanline phase/.

def get_spacing_and_phase(OPHS, xdir, ydir):
  # Given a list {OPHS} of filler elements, in arbtrary order, returns
  # estimtes of the average scanline spacing {ystep} (which should be
  # approximately the common trace width) and scanline phase {yphase}. 
  #
  # The phase should be the approximate {ydir} projection of the
  # lowest scanline in direction {ydir}.
  # 
  # Fails if the list is empty, or if the elements are not a proper raster
  # fill.
  return raster_IMP.get_spacing_and_phase(OPHS, xdir, ydir)

def scanline_index(oph, xdir, ydir, ystep, yphase):
  # Returns the index of the scanline that contains the raster fill element {oph}.
  # Assumes that the scanline  projections in the {ydir} direction are
  # approximately {yphase + isc*ystep}. 
  return raster_IMP.scanline_index(oph, xdir, ydir, ystep, yphase)

def sort_by_scanline(OPHS, xdir, ydir, ystep, yphase):
  # Given a list {OPHS} of filler elements, in arbtrary order, returns a
  # copy of the list with the same rasters sorted by increasing scanline
  # order.  Assumes that the rasters are parallel to the unit vector {xdir},
  # and that the projecttion of scanline with index {isc} on the perpendicular 
  # direction {ydir} is approximately {yphase + isc*ystep}.
  return raster_IMP.sort_by_scanline(OPHS, xdir, ydir, ystep, yphase)

def separate_by_scanline(OPHS, xdir, ydir, ystep, yphase):
  # Given a list {OPHS} of filler elements, in scanline order, returns a
  # list {SCS} of sub-lists, wehere each sub-list {SCS[isc]} contains
  # the indics into {OPHS} of the fillers on the scan-line with index
  # {isc}, also in scan-line order. 
  #
  # Assumes that the rasters are parallel to the unit vector {xdir};
  # that the projection of scanline with index {isc} on the
  # perpendicular direction {ydir} is approximately {yphase +
  # isc*ystep}; and that the scanline indices are all non-negative.
  return raster_IMP.separate_by_scanline(OPHS, xdir, ydir, ystep, yphase)

def make_raster_raster_link(oph0, oph1, mp_link, name):
  # Creates a link path betwen the initial points of the fill elements
  # {oph0} and {oph1}. Attaches the link to the lists of links of the
  # two paths with {raster_hp.add_link}.
  #
  # The link path consists of a single trace with parameters {mp_link}
  # The trace will be named "T{name}" and the path "P{name}".
  #
  # The link is created only if the two traces satisfy the conditions
  # of {move.connector}, otherwise the procedure does nothing.
  # Usually, that means {oph0} and {oph1} are parallel and oriented in 
  # the same direction.
  #
  # The procedure returns the created link, or {None} if it was not created.
  return raster_IMP.make_raster_raster_link(oph0, oph1, mp_link, name)
  
def create_all_raster_raster_links(OPHS, xdir, ydir, mp_link):
  # Given a list {OPHS} of raster fill elements, in arbitrary order,
  # creates link paths between endpoints of rasters in adjacent
  # scanlines, when appropriate. Returns a list of those link paths.
  #
  # Specifically, the procedure calls {make_raster_raster_link} for any 
  # two rasters {oph0,oph1} in consecutive scanlines.
  #
  return raster_IMP.create_all_raster_raster_links(OPHS, xdir, ydir, mp_link)

def create_all_raster_raster_contacts(OPHS, xdir, ydir):
  # Given a list {OPHS} of raster fill elements, in arbitrary order,
  # creates contacts between rasters in adjacent
  # scanlines that have significant length of shared border.
  # Returns a list of those contacts.
  #
  # The procedure also attaches the contact to the lists of contacts
  # of the two paths, with {path_hp.add_contact}.
  #
  return raster_IMP.create_all_raster_raster_contacts(OPHS, xdir, ydir)