# HotPath-related path attributes.
# Last edited on 2021-10-04 00:11:33 by stolfi

import path_hp_IMP
import path
import move
import contact
import block

# In addition to the fields defined in the {path} module, each {Path}
# object also has some additional fields that are used during the
# {hotpath.best_path} algorithm. This module gives access to those
# attributes.
#
# These attributes are not defined automatically. Their initial values
# are undefined and must be properly defined by the {set_*} procedures
# below, just before or during the heuristic.
#
# Most of these procedures take an oriented path parameter {oph} for convenience, but 
# the fields are associated with the underlying {Path} object and therefore
# they are automatically shared by {oph} and {path.rev(oph)}.  The orientation
# of {oph} may however affect how the information is stored or retrieved.
# However those fields are not shared by new paths derived from {oph}, e. g.
# through {path.concat}, {path.displace}, or {path.shift_contour}.

# PATH CONTACTS

# Each {Path} object {ph} may have two lists of {Contact} objects
# assigned to it accesded with {get_contacts(oph,i)} below. When reading
# a set of raster-type filling elements, the two lists are the contacts
# with the rasters on the scanline "below" it and with those on the
# scanline "above" it, respectively, for a specified "up" direction. 

def clear_contacts(oph):
  # Clears the contact lists associated with the underlying {Path}
  # object of the oriented path {oph}.
  return path_hp_IMP.clear_contacts(oph)

def get_contacts(oph, i):
  # Returns the list of contacts on side {i} of the {Path} object 
  # underlying {oph}, as assigned by {add_contact}.
  return path_hp_IMP.get_contacts(oph, i)

def add_contact(oph, i, ct):
  # Appends {ct} to the list of contacts on side {i} of {oph}.
  # The list must have been initialized previously by {clear_contacts}.
  path_hp_IMP.add_contact(oph, i, ct)
  
# OWNING BLOCK

# Each {Path} object {ph} can be assigned a {Block} object {bc}. During
# the tool-path construction algorithms, for example, the block {bc} is
# such that {choice(bc,ich)} is {ph} or its reversal, for at least one
# index {ich}.

def get_block(oph):
  # Returns the /owning block/ of the {Path} object underlying the
  # oriented path {oph}.
  return path_hp_IMP.get_block(oph)

def set_block(oph, bc):
  # Sets the owning block of the {Path} object underlying {oph} to {bc}. 
  # See {get_block} above.
  path_hp_IMP.set_block(oph, bc)
  
# BLOCKS INSIDE CONTOUR PATHS

# Each contour path {cr} (closed orented path that is part of the slice's
# boundary) can be associated to a set of candidate filling blocks that
# are contained in {cr} but not in any other contour path inside {cr}. These
# links are associated to the underlying {Path} object of {cr} by
# {assign_blocks_to_contours} below. The orientation of {cr} is ignored,
# so that blocks are automatically shared with {path.rev(cr)}; but they
# are not reserved by any operation that creates a new {Path} object,
# such as {path.shift_contour} or {path.displace}.

def assign_blocks_to_contours(OCRS, BCS):
  # The arguments are a list {OCRS} of contour paths (closed oriented
  # paths objects) and a list {BCS} of {Block} objects. The procedure
  # attaches to each contour path {ocr} in {OCRS} a list of the blocks of
  # {BCS} that are contained in {ocr} and in no other contour path that
  # is contained in {ocr}.
  #
  # The procedure assumes that the contour paths do not intersect and that
  # the moves of each block are all strctly inside or strictly outside
  # each contour path. The procedure fails if some block is not inside any
  # contour path.
  path_hp_IMP.assign_blocks_to_contours(OCRS, BCS)

def get_blocks_in_contour(ocr):
  # Returns the list of blocks that were assined to contour path {ocr}
  # by {assign_blocks_to_contours}.
  return path_hp_IMP.get_blocks_in_contour(ocr)